akm-cli 0.7.5 → 0.8.0-rc.3

package/dist/commands/lint/task-linter.js

@@ -0,0 +1,47 @@
+import { BaseLinter } from "./base-linter";
+/**
+ * Linter for `tasks/` assets.
+ *
+ * Tasks are `.md` files with YAML frontmatter. In addition to the base checks
+ * this linter validates the required task fields:
+ *
+ *   - `schedule`  (string, non-empty) — cron expression or `@`-alias
+ *   - `enabled`   (boolean)
+ *   - At least one of: `prompt` or `workflow` field present
+ *
+ * All issues are reported as `invalid-task-frontmatter` and are **not**
+ * auto-fixable. Cron expression syntax validation is intentionally out of
+ * scope (that belongs to `parseSchedule()`).
+ */
+export class TaskLinter extends BaseLinter {
+    types = ["tasks"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        // Only validate frontmatter fields when frontmatter is present.
+        if (ctx.frontmatter === null)
+            return issues;
+        const missing = [];
+        // schedule: must be present and non-empty
+        if (!("schedule" in ctx.data) || typeof ctx.data.schedule !== "string" || ctx.data.schedule.trim() === "") {
+            missing.push("schedule");
+        }
+        // enabled: must be present (boolean — value of false is valid)
+        if (!("enabled" in ctx.data)) {
+            missing.push("enabled");
+        }
+        // At least one of: prompt or workflow
+        const hasTarget = "prompt" in ctx.data || "workflow" in ctx.data;
+        if (!hasTarget) {
+            missing.push("prompt or workflow");
+        }
+        if (missing.length > 0) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "invalid-task-frontmatter",
+                detail: `missing required fields: ${missing.join(", ")}`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/lint/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/lint/vault-key-rules.js

@@ -0,0 +1,67 @@
+/**
+ * Vault security lint rules — flags known-dangerous environment variable names.
+ *
+ * These env var names, when present as vault keys, indicate the vault can be
+ * used to hijack process execution via loader injection, path override, or
+ * shell/runtime startup hooks.  The lint pass emits a warning-level finding;
+ * it does NOT block vault load or `akm add` installation.
+ */
+import { listKeys } from "../vault";
+// ── Dangerous key set ─────────────────────────────────────────────────────────
+export const DANGEROUS_VAULT_KEYS = new Set([
+    // Dynamic linker hijacking (Linux)
+    "LD_PRELOAD",
+    "LD_LIBRARY_PATH",
+    "LD_AUDIT",
+    "LD_DEBUG",
+    // Dynamic linker hijacking (macOS)
+    "DYLD_INSERT_LIBRARIES",
+    "DYLD_LIBRARY_PATH",
+    "DYLD_FRAMEWORK_PATH",
+    // Shell and command resolution
+    "PATH",
+    "BASH_ENV",
+    "ENV",
+    "PROMPT_COMMAND",
+    "PS1",
+    "PS2",
+    // Language runtime hijacking
+    "NODE_OPTIONS",
+    "NODE_PATH",
+    "PYTHONSTARTUP",
+    "PYTHONPATH",
+    "PYTHONINSPECT",
+    "RUBYLIB",
+    "RUBYOPT",
+    "PERL5LIB",
+    "PERL5OPT",
+    "JAVA_TOOL_OPTIONS",
+    "JDK_JAVA_OPTIONS",
+    "_JAVA_OPTIONS",
+]);
+// ── Checker ───────────────────────────────────────────────────────────────────
+/**
+ * Inspect a vault `.env` file and return a lint finding for every key whose
+ * name appears in `DANGEROUS_VAULT_KEYS`.
+ *
+ * @param vaultPath  Absolute path to the `.env` file.
+ * @param relPath    Stash-relative path used as the `file` field in findings
+ *                   (e.g. `"vaults/prod.env"`).
+ * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
+ *                   the finding message.
+ */
+export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
+    const { keys } = listKeys(vaultPath);
+    const issues = [];
+    for (const key of keys) {
+        if (!DANGEROUS_VAULT_KEYS.has(key))
+            continue;
+        issues.push({
+            file: relPath,
+            issue: "dangerous-vault-key",
+            detail: `Vault key \`${key}\` can be used to hijack process execution when injected via \`akm vault run\`. Vault ref: ${vaultRef}. Review this vault file before running \`akm vault run\` commands against untrusted stashes.`,
+            fixed: false,
+        });
+    }
+    return issues;
+}

package/dist/commands/lint/workflow-linter.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import { BaseLinter } from "./base-linter";
+const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
+/**
+ * Linter for `workflows/` assets.
+ *
+ * Extra check beyond base:
+ *   - `placeholder-stub`: body contains a known placeholder string.
+ *     Fix: delete the file.
+ */
+export class WorkflowLinter extends BaseLinter {
+    types = ["workflows"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const placeholderMatch = this.#checkPlaceholderStub(ctx.body);
+        if (placeholderMatch) {
+            if (ctx.fix) {
+                try {
+                    fs.unlinkSync(ctx.filePath);
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "placeholder-stub",
+                        detail: `deleted: found "${placeholderMatch}"`,
+                        fixed: true,
+                    });
+                }
+                catch (e) {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "placeholder-stub",
+                        detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                        fixed: false,
+                    });
+                }
+                return issues;
+            }
+            issues.push({
+                file: ctx.relPath,
+                issue: "placeholder-stub",
+                detail: `placeholder text: "${placeholderMatch}"`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+    #checkPlaceholderStub(body) {
+        for (const placeholder of PLACEHOLDER_STRINGS) {
+            if (body.includes(placeholder))
+                return placeholder;
+        }
+        return null;
+    }
+}

package/dist/commands/lint.js

@@ -0,0 +1 @@
+export { akmLint } from "./lint/index";

package/dist/commands/proposal.js

@@ -12,7 +12,7 @@ import { resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { archiveProposal, createProposal, diffProposal, getProposal, listProposals, promoteProposal, validateProposal, } from "../core/proposals";
+import { archiveProposal, createProposal, diffProposal, getProposal, listProposals, promoteProposal, resolveProposalId, validateProposal, } from "../core/proposals";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
     if (stashDir)
@@ -43,7 +43,8 @@ export function akmProposalShow(options) {
 export async function akmProposalAccept(options) {
     const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
-    const result = await promoteProposal(stash, config, options.id, { target: options.target }, options.ctx);
+    const resolvedId = resolveProposalId(stash, options.id).id;
+    const result = await promoteProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
     // Emit `promoted` to the events stream so observers (audit, dashboards,
     // sync) see the accept happen. Only emit on the happy path — promotion
     // throws on validation failure, so reaching this point means the asset
@@ -69,11 +70,11 @@ export async function akmProposalAccept(options) {
 }
 export function akmProposalReject(options) {
     const stash = resolveStash(options.stashDir);
-    const existing = getProposal(stash, options.id);
+    const existing = resolveProposalId(stash, options.id);
     if (existing.status !== "pending") {
-        throw new UsageError(`Proposal ${options.id} is not pending (current status: ${existing.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
+        throw new UsageError(`Proposal ${existing.id} is not pending (current status: ${existing.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
     }
-    const updated = archiveProposal(stash, options.id, "rejected", options.reason, options.ctx);
+    const updated = archiveProposal(stash, existing.id, "rejected", options.reason, options.ctx);
     appendEvent({
         eventType: "rejected",
         ref: updated.ref,
@@ -96,8 +97,8 @@ export function akmProposalReject(options) {
 export function akmProposalDiff(options) {
     const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
-    const proposal = getProposal(stash, options.id);
-    const diff = diffProposal(stash, config, options.id, { target: options.target });
+    const proposal = resolveProposalId(stash, options.id);
+    const diff = diffProposal(stash, config, proposal.id, { target: options.target });
     return {
         schemaVersion: 1,
         id: proposal.id,

package/dist/commands/propose.js

@@ -12,34 +12,19 @@
 import { parseAssetRef } from "../core/asset-ref";
 import { TYPE_DIRS } from "../core/asset-spec";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
 import { createProposal } from "../core/proposals";
-import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { runAgent, } from "../integrations/agent";
+import { resolveProcessAgentProfile } from "../integrations/agent/config";
 import { buildProposePrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
-function loadAgentConfigFromDisk() {
-    const config = loadConfig();
-    return parseAgentConfig(config.agent);
-}
-function resolveProfile(options) {
-    if (options.agentProfile)
-        return options.agentProfile;
-    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-    return requireAgentProfile(agent, options.profile);
-}
+import { runAgentSdk } from "../integrations/agent/sdk-runner";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "./agent-support";
 function failureEnvelope(result, type, name, fallbackReason = "non_zero_exit") {
-    const reason = result.reason ?? fallbackReason;
     return {
-        schemaVersion: 1,
-        ok: false,
-        reason,
-        error: result.error ?? `agent failure (${reason})`,
+        ...baseFailureFields(result, fallbackReason),
         type,
         name,
-        exitCode: result.exitCode,
-        ...(result.stdout ? { stdout: result.stdout } : {}),
-        ...(result.stderr ? { stderr: result.stderr } : {}),
     };
 }
 export async function akmPropose(options) {
@@ -68,9 +53,31 @@ export async function akmPropose(options) {
         },
     });
     // 2. Resolve profile.
+    // When an explicit --profile flag is given, honour it directly (existing
+    // behaviour). Otherwise use resolveProcessAgentProfile so that per-process
+    // agent config (agent.processes["propose"]) is picked up automatically.
     let profile;
+    let resolvedTimeoutMs = options.timeoutMs;
     try {
-        profile = resolveProfile(options);
+        if (options.agentProfile) {
+            // Test seam: injected profile bypasses all config.
+            profile = options.agentProfile;
+        }
+        else if (options.profile) {
+            // Explicit --profile flag wins over process config.
+            profile = resolveAgentProfile(options);
+        }
+        else {
+            // Use per-process config resolution (falls back to agent.default).
+            const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+            const processName = options.agentProcess ?? "propose";
+            const resolved = resolveProcessAgentProfile(processName, agent);
+            profile = resolved.profile;
+            // Only apply process-resolved timeoutMs when caller didn't supply one.
+            if (resolvedTimeoutMs === undefined) {
+                resolvedTimeoutMs = resolved.timeoutMs;
+            }
+        }
     }
     catch (err) {
         if (err instanceof ConfigError || err instanceof UsageError)
@@ -91,14 +98,35 @@ export async function akmPropose(options) {
     // 4. Spawn the agent.
     // Real agent runs use interactive mode so file tools can write the draft.
     // Injected/custom spawns still need captured stdout for JSON payload tests.
-    const runOptions = {
-        stdio: options.runAgentOptions?.spawn ? "captured" : "interactive",
-        parseOutput: "text",
-        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-        ...(options.runAgentOptions ?? {}),
-    };
-    const result = await runAgent(profile, prompt, runOptions);
+    // Use callAi for the unified AI dispatch path (agent CLI preferred, LLM HTTP fallback).
+    const useCustomSpawn = Boolean(options.runAgentOptions?.spawn);
+    let result;
+    if (useCustomSpawn) {
+        // Test seam: use raw runAgent with injected spawn so tests remain deterministic.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+            ...(options.runAgentOptions ?? {}),
+        };
+        result = await runAgent(profile, prompt, runOptions);
+    }
+    else {
+        // Production path: dispatch directly to the appropriate runner.
+        const runOptions = {
+            stdio: resolvedDraftPath ? "interactive" : "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+        };
+        result = profile.sdkMode
+            ? await runAgentSdk(profile, prompt ?? "", runOptions)
+            : await runAgent(profile, prompt, runOptions);
+    }
     if (!result.ok) {
+        // B3: ENOENT / not-found gives an actionable hint.
+        if (isEnoentFailure(result)) {
+            return { ...failureEnvelope(result, options.type, options.name), error: enoentHintMessage(profile.bin) };
+        }
         return failureEnvelope(result, options.type, options.name);
     }
     // 5. Resolve the proposal content.
@@ -115,6 +143,21 @@ export async function akmPropose(options) {
         };
     }
     else {
+        // B1: When interactive mode was used and stdout is empty, the agent did not
+        // write the draft file and stdout was not captured — surface an actionable error.
+        const stdioWasInteractive = !useCustomSpawn;
+        if (stdioWasInteractive && (result.stdout ?? "") === "") {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: "Agent did not write draft file and stdout was not captured (interactive mode). Check that the agent CLI understood the file-write instruction, or configure a headless profile with stdio: 'captured'.",
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
         try {
             payload = parseAgentProposalPayload(result.stdout ?? "");
         }

package/dist/commands/reflect.js

@@ -19,16 +19,22 @@
  * a committed asset, and the `accept` flow is the bridge.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
 import { lintLessonContent } from "../core/lesson-lint";
+import { stripMarkdownFences } from "../core/markdown";
 import { createProposal } from "../core/proposals";
 import { lookup } from "../indexer/indexer";
-import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { runAgent, } from "../integrations/agent";
+import { resolveProcessAgentProfile } from "../integrations/agent/config";
 import { buildReflectPrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
+import { runAgentSdk } from "../integrations/agent/sdk-runner";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "./agent-support";
+import { deriveLessonRef } from "./distill";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -45,7 +51,7 @@ function readRecentFeedback(ref) {
         for (const event of result.events.slice(-limit)) {
             const md = (event.metadata ?? {});
             const signal = typeof md.signal === "string" ? md.signal : "?";
-            const note = typeof md.note === "string" ? md.note : typeof md.reason === "string" ? md.reason : "";
+            const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
             const details = note ? `[${signal}] ${note}` : `[${signal}]`;
             lines.push(!ref && event.ref ? `${event.ref} ${details}` : details);
         }
@@ -68,45 +74,83 @@ function buildSchemaHints(type, content) {
     const report = lintLessonContent(content, "reflect");
     return report.findings.map((f) => `[${f.kind}] ${f.message}`);
 }
+function hasRelatedSkillSource(content, skillRef) {
+    const parsed = parseFrontmatter(content);
+    const sources = parsed.data.sources;
+    return Array.isArray(sources) && sources.some((source) => typeof source === "string" && source.trim() === skillRef);
+}
+async function readRelatedLessons(stash, ref, parsedRef) {
+    if (parsedRef.type !== "skill")
+        return [];
+    const related = new Map();
+    const derivedLessonRef = deriveLessonRef(ref);
+    const candidateRefs = new Set([derivedLessonRef]);
+    const derivedLessonPath = path.join(stash, "lessons", `${derivedLessonRef.slice("lesson:".length)}.md`);
+    if (fs.existsSync(derivedLessonPath)) {
+        related.set(derivedLessonRef, { ref: derivedLessonRef, content: fs.readFileSync(derivedLessonPath, "utf8") });
+    }
+    try {
+        const feedbackEvents = readEvents({ type: "distill_invoked", ref }).events;
+        for (const event of feedbackEvents) {
+            const lessonRef = typeof event.metadata?.lessonRef === "string" ? event.metadata.lessonRef : undefined;
+            if (lessonRef?.startsWith("lesson:"))
+                candidateRefs.add(lessonRef);
+        }
+    }
+    catch {
+        // Best effort only.
+    }
+    for (const candidateRef of candidateRefs) {
+        try {
+            const entry = await lookup(parseAssetRef(candidateRef));
+            if (!entry?.filePath || !fs.existsSync(entry.filePath))
+                continue;
+            const content = fs.readFileSync(entry.filePath, "utf8");
+            related.set(candidateRef, { ref: candidateRef, content });
+        }
+        catch {
+            // Index miss is non-fatal.
+        }
+    }
+    try {
+        const lessonsDir = path.join(stash, "lessons");
+        if (fs.existsSync(lessonsDir)) {
+            for (const fileName of fs.readdirSync(lessonsDir)) {
+                if (!fileName.endsWith(".md"))
+                    continue;
+                const content = fs.readFileSync(path.join(lessonsDir, fileName), "utf8");
+                if (!hasRelatedSkillSource(content, ref))
+                    continue;
+                const lessonName = fileName.slice(0, -3);
+                const lessonRef = `lesson:${lessonName}`;
+                if (!related.has(lessonRef)) {
+                    related.set(lessonRef, { ref: lessonRef, content });
+                }
+            }
+        }
+    }
+    catch {
+        // Best effort only.
+    }
+    return [...related.values()];
+}
 function fallbackPayloadFromRawContent(stdout, ref) {
     if (!ref)
         return undefined;
-    const trimmed = stripMarkdownFence(stdout).trim();
+    const trimmed = stripMarkdownFences(stdout).trim();
     if (!trimmed)
         return undefined;
     if (!looksLikeAssetContent(trimmed))
         return undefined;
     return { ref, content: trimmed };
 }
-function stripMarkdownFence(stdout) {
-    const trimmed = stdout.trim();
-    const match = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```$/i);
-    return match?.[1] ?? trimmed;
-}
 function looksLikeAssetContent(value) {
     return value.startsWith("#") || value.startsWith("---");
 }
-function loadAgentConfigFromDisk() {
-    const config = loadConfig();
-    return parseAgentConfig(config.agent);
-}
-function resolveProfile(options) {
-    if (options.agentProfile)
-        return options.agentProfile;
-    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-    return requireAgentProfile(agent, options.profile);
-}
 function failureEnvelope(result, ref, fallbackReason = "non_zero_exit") {
-    const reason = result.reason ?? fallbackReason;
     return {
-        schemaVersion: 1,
-        ok: false,
-        reason,
-        error: result.error ?? `agent failure (${reason})`,
+        ...baseFailureFields(result, fallbackReason),
         ...(ref ? { ref } : {}),
-        exitCode: result.exitCode,
-        ...(result.stdout ? { stdout: result.stdout } : {}),
-        ...(result.stderr ? { stderr: result.stderr } : {}),
     };
 }
 export async function akmReflect(options = {}) {
@@ -138,9 +182,32 @@ export async function akmReflect(options = {}) {
     }
     // 3. Resolve agent profile. ConfigError surfaces as a thrown error so the
     // CLI dispatcher renders the standard envelope.
+    //
+    // When an explicit --profile flag is given, honour it directly (existing
+    // behaviour). Otherwise use resolveProcessAgentProfile so that per-process
+    // agent config (agent.processes["reflect"]) is picked up automatically.
     let profile;
+    let resolvedTimeoutMs = options.timeoutMs;
     try {
-        profile = resolveProfile(options);
+        if (options.agentProfile) {
+            // Test seam: injected profile bypasses all config.
+            profile = options.agentProfile;
+        }
+        else if (options.profile) {
+            // Explicit --profile flag wins over process config.
+            profile = resolveAgentProfile(options);
+        }
+        else {
+            // Use per-process config resolution (falls back to agent.default).
+            const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+            const processName = options.agentProcess ?? "reflect";
+            const resolved = resolveProcessAgentProfile(processName, agent);
+            profile = resolved.profile;
+            // Only apply process-resolved timeoutMs when caller didn't supply one.
+            if (resolvedTimeoutMs === undefined) {
+                resolvedTimeoutMs = resolved.timeoutMs;
+            }
+        }
     }
     catch (err) {
         if (err instanceof ConfigError || err instanceof UsageError)
@@ -153,6 +220,7 @@ export async function akmReflect(options = {}) {
     // local opencode models and caused proposal generation failures.
     const feedback = readRecentFeedback(options.ref);
     const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(stash, options.ref, parsedRef) : [];
     const prompt = buildReflectPrompt({
         ...(options.ref ? { ref: options.ref } : {}),
         ...(parsedRef?.type ? { type: parsedRef.type } : {}),
@@ -160,17 +228,40 @@ export async function akmReflect(options = {}) {
         ...(assetContent !== undefined ? { assetContent } : {}),
         ...(feedback.length > 0 ? { feedback } : {}),
         ...(schemaHints.length > 0 ? { schemaHints } : {}),
+        ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
         ...(options.task ? { task: options.task } : {}),
+        ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
     });
     // 5. Spawn the agent.
-    const runOptions = {
-        stdio: "captured",
-        parseOutput: "text",
-        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-        ...(options.runAgentOptions ?? {}),
-    };
-    const result = await runAgent(profile, prompt, runOptions);
+    // Fall back to raw runAgent when a custom spawn function is injected (test seam).
+    // Production path dispatches directly to runAgentSdk or runAgent.
+    let result;
+    if (options.runAgentOptions?.spawn) {
+        // Test seam: use raw runAgent with injected spawn so tests remain deterministic.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+            ...(options.runAgentOptions ?? {}),
+        };
+        result = await runAgent(profile, prompt, runOptions);
+    }
+    else {
+        // Production path: dispatch directly to the appropriate runner.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+        };
+        result = profile.sdkMode
+            ? await runAgentSdk(profile, prompt ?? "", runOptions)
+            : await runAgent(profile, prompt, runOptions);
+    }
     if (!result.ok) {
+        // B3: ENOENT / not-found gives an actionable hint.
+        if (isEnoentFailure(result)) {
+            return { ...failureEnvelope(result, options.ref), error: enoentHintMessage(profile.bin) };
+        }
         return failureEnvelope(result, options.ref);
     }
     // 6. Resolve the proposal content from stdout JSON.
@@ -208,6 +299,15 @@ export async function akmReflect(options = {}) {
         },
     };
     const proposal = createProposal(stash, createInput, options.ctx);
+    appendEvent({
+        eventType: "reflect_completed",
+        ref: proposal.ref,
+        metadata: {
+            proposalId: proposal.id,
+            source: "reflect",
+            agentProfile: profile.name,
+        },
+    });
     return {
         schemaVersion: 1,
         ok: true,

package/dist/commands/registry-search.js

@@ -1,5 +1,5 @@
 import { toErrorMessage } from "../core/common";
-import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { DEFAULT_CONFIG } from "../core/config";
 import { warn } from "../core/warn";
 import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
@@ -133,7 +133,7 @@ export function resolveRegistries(configRegistries) {
         }
         return entries;
     }
-    const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
+    const registries = configRegistries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
 }
 // ── Provider resolution ─────────────────────────────────────────────────────