akm-opencode 0.7.2 → 0.7.3

package/README.md

@@ -36,7 +36,7 @@ The plugin exposes **20 high-value tools**. Long-tail verbs (`add`, `save`, `imp
 | `akm_reflect` | Generate a reflection proposal via the configured agent CLI; output lands in the proposal queue only |
 | `akm_propose` | Generate a new-asset proposal via the configured agent CLI; the result is `quality:"proposed"` until accepted |
 | `akm_distill` | Distill an AKM ref (typically `memory:*` or `knowledge:*`) into a proposed `lesson` (gated by `llm.features.feedback_distillation`) |
-| `akm_setup` | Detect installed agent CLIs (`opencode`, `claude`, `codex`, `gemini`, `aider`) and persist `agent.default`. Required once per machine for `akm_reflect` / `akm_propose` |
+| `akm_init` | Initialize AKM's working stash directory and persist `stashDir` in config. This is the agent-safe initialization path; interactive `akm setup` is human-facing |
 | `akm_help` | Discover the right `akm` CLI invocation for non-first-class verbs. Returns a curated quick-reference table plus live `akm <subcommand> --help` output |
 
 ## Compound-engineering hooks
@@ -47,8 +47,8 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Event | What happens |
 | --- | --- |
-| **`session.created`** (event hook) | Warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions see relevant stash context before the first user message. |
-| **`chat.message`** | Runs `akm curate "<prompt>" --run <sessionID>` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
+| **`session.created`** (event hook) | Sets `agent.default` to `opencode` when missing, warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions start with relevant stash context. |
+| **`chat.message`** | Records user feedback/memory intent and appends a short reminder to use `akm_search` / `akm_curate` when more stash context is needed. It does not auto-run AKM CLI lookups on every message. |
 | **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, pending proposal summaries, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
 | **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
 | **`permission.ask`** / **`command.execute.before`** | Detects risky raw `akm` CLI commands executed through shell/commands and denies them until the user explicitly approves the exact operation. |
@@ -61,7 +61,7 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `AKM_AUTO_CURATE` | `1` | Set to `0` to disable automatic `akm curate` on user messages. |
+| `AKM_AUTO_CURATE` | `1` | Set to `0` to disable automatic `akm curate` on user messages. Session start no longer auto-curates. |
 | `AKM_AUTO_FEEDBACK` | `1` | Set to `0` to disable automatic `akm feedback` on tool success/failure. |
 | `AKM_AUTO_HINTS` | `1` | Set to `0` to skip injecting `akm hints` at session start. |
 | `AKM_AUTO_MEMORY` | `1` | Set to `0` to disable automatic session-summary memories. |

package/index.ts

@@ -71,7 +71,7 @@ const AKM_WORKFLOW_INSTRUCTION = [
   "3. Record `akm_feedback` after the result is known.",
   "4. Use the dedicated v0.7.0 tools for the proposal flow: `akm_proposal` (list/show/diff/accept/reject), `akm_reflect`, `akm_propose`, and `akm_distill`. Fall back to `akm_help` for any verb without a dedicated tool.",
   "5. Treat `lesson:*` as first-class durable learning assets — they are produced by `akm_distill <ref>` as proposals and accepted via `akm_proposal action=accept`.",
-  "6. Run `akm_setup` once on a fresh machine to detect installed agent CLIs and persist `agent.default`. Reflect/propose require it.",
+  "6. Use `akm_init` when you need to create the working stash or persist `stashDir`. Do not use `akm setup` from an agent; it is interactive and human-facing.",
   `7. ${PROPOSED_QUALITY_WARNING}`,
   "8. Never accept or reject proposals, push saves, remove sources, or access vault values without explicit user approval.",
 ].join("\n")
@@ -225,42 +225,17 @@ function needsAgentSetup(message: string): boolean {
 
 function addAgentSetupGuidance(message: string): string {
   if (!needsAgentSetup(message)) return message
-  if (/\bakm_setup\b|\bakm setup\b/i.test(message)) return message
-  return `${message}. Run akm_setup to detect an installed agent CLI and persist agent.default. If none is installed yet, install one of: opencode, claude, codex, gemini, aider.`
+  if (/\bakm init\b|\bakm_init\b|\bakm setup\b/i.test(message)) return message
+  return `${message}. Agents should not run akm setup because it is interactive. The plugin should set agent.default to the current platform when it is missing; if interactive configuration is still needed, ask the user to run akm setup manually. Use akm_init for agent-safe stash initialization.`
 }
 
-function toLogString(value: unknown): string | undefined {
-  if (typeof value === "string") return value
-  if (value instanceof Buffer) return value.toString("utf8")
-  return undefined
-}
-
-function getExecStatus(error: unknown): number | null {
-  if (!error || typeof error !== "object" || !("status" in error)) return null
-  const status = (error as { status?: unknown }).status
-  return typeof status === "number" ? status : null
-}
-
-async function writePluginLog(client: LogCapableClient, level: LogLevel, message: string, extra: Record<string, unknown>) {
-  try {
-    await client.app.log({
-      query: typeof extra.directory === "string" ? { directory: extra.directory } : undefined,
-      body: {
-        service: "akm-opencode",
-        level,
-        message,
-        extra,
-      },
-    })
-  } catch {
-    // Avoid breaking the TUI if logging itself fails.
-  }
-}
-
-async function runAgentSetup(client: LogCapableClient, meta: { directory?: string; sessionID?: string; trigger: string; force?: boolean }): Promise<boolean> {
+async function ensurePlatformAgentDefault(
+  client: LogCapableClient,
+  meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
+): Promise<boolean> {
   const command = resolveAkmCommand()
   if (typeof command !== "string") {
-    await writePluginLog(client, "warn", "AKM agent setup skipped", {
+    await writePluginLog(client, "warn", "AKM agent default check skipped", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
@@ -270,59 +245,56 @@ async function runAgentSetup(client: LogCapableClient, meta: { directory?: strin
     return false
   }
 
-  const args = ["setup"]
-  if (meta.force) args.push("--force")
-  args.push("--format", "json")
-
   try {
-    const stdout = execFileSync(command, args, {
+    const currentRaw = execFileSync(command, ["config", "get", "agent.default", "--format", "json"], {
       encoding: "utf8",
       timeout: 30_000,
     })
-    const parsed = safeJsonParse<{ ok?: boolean; error?: string }>(stdout)
-    if (parsed?.ok === false) {
-      await writePluginLog(client, "warn", "AKM agent setup reported an error", {
-        subsystem: "akm",
-        trigger: meta.trigger,
-        sessionID: meta.sessionID,
-        directory: meta.directory,
-        command,
-        args,
-        stdout,
-        error: parsed.error ?? "Unknown akm setup error",
-      })
-      return false
-    }
-    await writePluginLog(client, "info", "AKM agent setup completed", {
+    const parsed = safeJsonParse<unknown>(currentRaw)
+    const current = typeof parsed === "string"
+      ? parsed.trim()
+      : parsed && typeof parsed === "object"
+        ? typeof (parsed as Record<string, unknown>).value === "string"
+          ? ((parsed as Record<string, unknown>).value as string).trim()
+          : typeof (parsed as Record<string, unknown>)["agent.default"] === "string"
+            ? ((parsed as Record<string, unknown>)["agent.default"] as string).trim()
+            : ""
+        : ""
+    if (current) return true
+
+    execFileSync(command, ["config", "set", "agent.default", meta.platform, "--format", "json"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    })
+    await writePluginLog(client, "info", "AKM agent default initialized", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
       directory: meta.directory,
-      command,
-      args,
-      stdout,
+      agentDefault: meta.platform,
     })
     return true
   } catch (error: unknown) {
-    const message = addAgentSetupGuidance(formatCliError(error))
-    await writePluginLog(client, "warn", "AKM agent setup failed", {
+    await writePluginLog(client, "warn", "AKM agent default initialization failed", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
       directory: meta.directory,
-      command,
-      args,
-      error: message,
+      platform: meta.platform,
+      error: addAgentSetupGuidance(formatCliError(error)),
       stdout: toLogString((error as { stdout?: unknown }).stdout) ?? "",
-      stderr: toLogString((error as { stderr?: unknown }).stderr) ?? message,
+      stderr: toLogString((error as { stderr?: unknown }).stderr) ?? "",
     })
     return false
   }
 }
 
-async function ensureAgentSetup(client: LogCapableClient, meta: { directory?: string; sessionID?: string; trigger: string; force?: boolean }): Promise<boolean> {
+async function ensureAgentSetup(
+  client: LogCapableClient,
+  meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
+): Promise<boolean> {
   if (agentSetupPromise) return agentSetupPromise
-  const promise = runAgentSetup(client, meta)
+  const promise = ensurePlatformAgentDefault(client, meta)
   const trackedPromise = promise.finally(() => {
     if (agentSetupPromise === trackedPromise) agentSetupPromise = null
   })
@@ -330,6 +302,52 @@ async function ensureAgentSetup(client: LogCapableClient, meta: { directory?: st
   return trackedPromise
 }
 
+function isNotIndexedFeedbackError(message: string): boolean {
+  return /not in the current index|run ["'`]?akm index["'`]? and try again/i.test(message)
+}
+
+function toLogString(value: unknown): string | undefined {
+  if (typeof value === "string") return value
+  if (value instanceof Buffer) return value.toString("utf8")
+  return undefined
+}
+
+function getExecStatus(error: unknown): number | null {
+  if (!error || typeof error !== "object" || !("status" in error)) return null
+  const status = (error as { status?: unknown }).status
+  return typeof status === "number" ? status : null
+}
+
+async function writePluginLog(client: LogCapableClient, level: LogLevel, message: string, extra: Record<string, unknown>) {
+  try {
+    await client.app.log({
+      query: typeof extra.directory === "string" ? { directory: extra.directory } : undefined,
+      body: {
+        service: "akm-opencode",
+        level,
+        message,
+        extra,
+      },
+    })
+  } catch {
+    // Avoid breaking the TUI if logging itself fails.
+  }
+}
+
+async function logHookFailure(
+  client: LogCapableClient,
+  hook: string,
+  error: unknown,
+  extra?: Record<string, unknown>,
+) {
+  await writePluginLog(client, "error", `AKM ${hook} hook failed`, {
+    subsystem: "hook",
+    hook,
+    error: formatCliError(error),
+    ...extra,
+  })
+}
+
 function nowIso(): string {
   return new Date().toISOString()
 }
@@ -431,9 +449,20 @@ function runCurate(args: string[]): string | null {
   return body || null
 }
 
-function runCurateForPrompt(text: string, sessionID?: string): string | null {
+async function runCurateLogged(
+  client: LogCapableClient,
+  args: string[],
+  meta: CliLogMeta & { operation: string },
+): Promise<string | null> {
+  return runCliSyncBestEffort(client, args, AKM_CURATE_TIMEOUT_MS, {
+    ...meta,
+    subsystem: "curation",
+  })
+}
+
+async function runCurateForPrompt(client: LogCapableClient, text: string, sessionID?: string): Promise<string | null> {
   if (!text || text.length < AKM_CURATE_MIN_CHARS) return null
-  return runCurate(
+  return runCurateLogged(client,
     appendRunScopeArgs(
       [
         "--detail",
@@ -448,11 +477,12 @@ function runCurateForPrompt(text: string, sessionID?: string): string | null {
       ],
       sessionID,
     ),
+    { toolName: "chat.message", sessionID, operation: "prompt-curate" },
   )
 }
 
-function runCurateForSession(sessionID: string): string | null {
-  return runCurate(
+async function runCurateForSession(client: LogCapableClient, sessionID: string): Promise<string | null> {
+  return runCurateLogged(client,
     appendRunScopeArgs(
       [
         "--detail",
@@ -466,14 +496,17 @@ function runCurateForSession(sessionID: string): string | null {
       ],
       sessionID,
     ),
+    { toolName: "session.start", sessionID, operation: "session-curate" },
   )
 }
 
-function runHintsForSession(): string | null {
-  const result = runCliSyncRaw(["--format", "text", "-q", "hints"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) return null
-  const body = result.stdout.trim()
-  return body || null
+async function runHintsForSession(client: LogCapableClient, sessionID?: string): Promise<string | null> {
+  return runCliSyncBestEffort(client, ["--format", "text", "-q", "hints"], AKM_CURATE_TIMEOUT_MS, {
+    toolName: "session.start",
+    sessionID,
+    subsystem: "hints",
+    operation: "session-hints",
+  })
 }
 
 function summarizeWorkflowList(value: unknown): string | null {
@@ -507,10 +540,15 @@ function summarizeWorkflowList(value: unknown): string | null {
   return null
 }
 
-function runWorkflowSummaryForSession(): string | null {
-  const result = runCliSyncRaw(["--format", "json", "-q", "workflow", "list", "--active"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) return null
-  const parsed = parseMaybeJson(result.stdout)
+async function runWorkflowSummaryForSession(client: LogCapableClient, sessionID?: string): Promise<string | null> {
+  const raw = await runCliSyncBestEffort(client, ["--format", "json", "-q", "workflow", "list", "--active"], AKM_CURATE_TIMEOUT_MS, {
+    toolName: "session.start",
+    sessionID,
+    subsystem: "workflow",
+    operation: "active-workflow-summary",
+  })
+  if (!raw) return null
+  const parsed = parseMaybeJson(raw)
   const summary = summarizeWorkflowList(
     Array.isArray(parsed)
       ? parsed
@@ -547,14 +585,20 @@ function summarizeCuratorReportForContext(report: string): string {
   return `${report.slice(0, AKM_CURATOR_CONTEXT_MAX_CHARS).trimEnd()}\n\n[truncated for context]`
 }
 
-function getAkmStashDir(): string | undefined {
+async function getAkmStashDir(client?: LogCapableClient): Promise<string | undefined> {
   if (cachedAkmStashDir !== undefined) return cachedAkmStashDir || undefined
-  const result = runCliSyncRaw(["--format", "json", "-q", "config", "get", "stashDir"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) {
+  const raw = client
+    ? await runCliSyncBestEffort(client, ["--format", "json", "-q", "config", "get", "stashDir"], AKM_CURATE_TIMEOUT_MS, {
+      toolName: "shell.env",
+      subsystem: "config",
+      operation: "get-stash-dir",
+    })
+    : runCurate(["--format", "json", "-q", "config", "get", "stashDir"])
+  if (!raw) {
     cachedAkmStashDir = ""
     return undefined
   }
-  const parsed = parseMaybeJson(result.stdout)
+  const parsed = parseMaybeJson(raw)
   if (typeof parsed === "string" && parsed.trim()) {
     cachedAkmStashDir = parsed.trim()
     return cachedAkmStashDir
@@ -568,7 +612,6 @@ function getAkmStashDir(): string | undefined {
       }
     }
   }
-  const raw = result.stdout.trim()
   cachedAkmStashDir = raw || ""
   return cachedAkmStashDir || undefined
 }
@@ -602,6 +645,29 @@ function emitWorkflowTelemetry(client: LogCapableClient, level: LogLevel, eventT
   })
 }
 
+async function runCliSyncBestEffort(
+  client: LogCapableClient,
+  args: string[],
+  timeoutMs: number,
+  meta: CliLogMeta & { subsystem: string; operation: string },
+): Promise<string | null> {
+  const result = runCliSyncRaw(args, timeoutMs)
+  if (!result.ok) {
+    await writePluginLog(client, "warn", "AKM synchronous helper failed", {
+      subsystem: meta.subsystem,
+      operation: meta.operation,
+      toolName: meta.toolName,
+      sessionID: meta.sessionID,
+      directory: meta.directory,
+      args,
+      error: result.error,
+    })
+    return null
+  }
+  const body = result.stdout.trim()
+  return body || null
+}
+
 function noteRecentRefs(sessionID: string | undefined, refs: string[]) {
   if (!sessionID || refs.length === 0) return
   const state = retrospectiveState.get(sessionID) ?? { recentRefs: [] }
@@ -659,7 +725,7 @@ async function recordRetrospectiveFeedback(client: LogCapableClient, sessionID:
     sessionID,
   })
   const parsed = safeJsonParse<{ ok?: boolean }>(raw)
-  if (parsed?.ok !== false) {
+  if (parsed?.ok === true) {
     await emitWorkflowTelemetry(client, "info", "akm.feedback.recorded", {
       sessionID,
       toolName: "akm_feedback",
@@ -1490,32 +1556,7 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
   } catch (error: unknown) {
     let message = formatCliError(error)
     if (["akm_reflect", "akm_propose"].includes(meta.toolName) && needsAgentSetup(message)) {
-      const setupOk = await ensureAgentSetup(client, {
-        directory: meta.directory,
-        sessionID: meta.sessionID,
-        trigger: `${meta.toolName}:retry`,
-        force: true,
-      })
-      if (setupOk) {
-        try {
-          const stdout = execFileSync(command, fullArgs, {
-            encoding: "utf8",
-            timeout: 60_000,
-          })
-          await writePluginLog(client, "info", "AKM command recovered after setup", {
-            subsystem: "akm",
-            toolName: meta.toolName,
-            sessionID: meta.sessionID,
-            directory: meta.directory,
-            command,
-            args: fullArgs,
-          })
-          return recordSuccess(stdout)
-        } catch (retryError: unknown) {
-          error = retryError
-          message = formatCliError(retryError)
-        }
-      }
+      message = addAgentSetupGuidance(message)
     }
     message = addAgentSetupGuidance(message)
     await writePluginLog(client, "error", "AKM command failed", {
@@ -2116,10 +2157,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               directory,
               sessionID: sid,
               trigger: "session.created",
+              platform: "opencode",
             })
             warmIndexInBackground()
             if (AKM_AUTO_CURATE && !sessionCurated.has(sid)) {
-              const curated = runCurateForSession(sid)
+              const curated = await runCurateForSession(logClient, sid)
               if (curated) {
                 bumpCuratedVersion(sid)
                 sessionCurated.set(sid, curated)
@@ -2127,11 +2169,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             }
           }
           if (AKM_AUTO_HINTS && !sessionHints.has(sid)) {
-            const hints = runHintsForSession()
+            const hints = await runHintsForSession(logClient, sid)
             if (hints) sessionHints.set(sid, hints)
           }
           if (!sessionWorkflow.has(sid)) {
-            sessionWorkflow.set(sid, runWorkflowSummaryForSession() ?? "")
+            sessionWorkflow.set(sid, await runWorkflowSummaryForSession(logClient, sid) ?? "")
           }
           const proposalSummary = await getPendingProposalCount(logClient, sid)
           if (!proposalSummary.unsupported && proposalSummary.count > 0) {
@@ -2166,8 +2208,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             sessionBuffer.delete(sid)
           }
         }
-      } catch {
-        // Lifecycle hooks must never throw into the TUI.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "event", error)
       }
     },
     // Stop is the closest analogue to Claude's Stop/SubagentStop — the user or
@@ -2188,8 +2230,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           })
           await maybeIndexSessionMemory(logClient, sid, "stop", captured)
         }
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "stop", error)
       }
     },
     // experimental.chat.system.transform is how OpenCode exposes the
@@ -2228,8 +2270,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             sessionCuratedInjectedVersion.set(sid, curatedVersion)
           }
         }
-      } catch {
-        // Never break the turn because of a transform failure.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "experimental.chat.system.transform", error)
       }
     },
     "tool.execute.before": async (input, output) => {
@@ -2245,8 +2287,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           return
         }
         output.args = args
-      } catch {
-        // Never break tool execution from the pre-hook.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "tool.execute.before", error, {
+          toolName: input?.tool,
+          sessionID: input?.sessionID,
+        })
       }
     },
     "permission.ask": async (input, output) => {
@@ -2274,8 +2319,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           command,
           category: assessment.category,
         })
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "permission.ask", error, {
+          sessionID: input?.sessionID,
+          command: typeof input?.metadata?.command === "string" ? input.metadata.command : undefined,
+        })
       }
     },
     "command.execute.before": async (input, output) => {
@@ -2292,18 +2340,21 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           command,
           category: assessment.category,
         })
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "command.execute.before", error, {
+          sessionID: input?.sessionID,
+          command: input?.command,
+        })
       }
     },
     "shell.env": async (_input, output) => {
       try {
         output.env.AKM_PROJECT = worktree
         output.env.AKM_PLUGIN_VERSION = PLUGIN_VERSION
-        const stashDir = getAkmStashDir()
+        const stashDir = await getAkmStashDir(logClient)
         if (stashDir) output.env.AKM_STASH_DIR = stashDir
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "shell.env", error)
       }
     },
     "chat.message": async (input, output) => {
@@ -2319,12 +2370,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           text: truncateLogText(text),
         })
 
-        // Compound-engineering loop: on every user message, curate the stash and
-        // stash the result so experimental.chat.system.transform can inject it.
+        // Session-start curation already seeded context. On later user messages,
+        // inject only a small reminder instead of firing more automatic AKM CLI calls.
         if (AKM_AUTO_CURATE && input.sessionID) {
-          const curated = runCurateForPrompt(text, input.sessionID)
-          if (curated) {
-            sessionCurated.set(input.sessionID, curated)
+          const hint = "Need more AKM context? Use `akm_search` or `akm_curate` before writing from scratch."
+          const current = sessionCurated.get(input.sessionID) ?? ""
+          if (!current.includes(hint)) {
+            sessionCurated.set(input.sessionID, current ? `${current}\n\n${hint}` : hint)
             bumpCuratedVersion(input.sessionID)
           }
         }
@@ -2552,6 +2604,32 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (note) args.push("--note", note)
         args.push(...buildScopedArgs(context as unknown as Record<string, unknown>))
         const raw = await runCli(client as unknown as LogCapableClient, args, { toolName: "akm_feedback", sessionID: context.sessionID, directory: context.directory })
+        const parsed = safeJsonParse<{ ok?: boolean; error?: string }>(raw)
+        if (parsed?.ok === false) {
+          const error = parsed.error ?? "Unknown akm feedback error"
+          if (isNotIndexedFeedbackError(error)) {
+            await writePluginLog(logClient, "warn", "AKM feedback skipped", {
+              subsystem: "feedback",
+              toolName: "akm_feedback",
+              sessionID: context.sessionID,
+              directory: context.directory,
+              ref,
+              sentiment,
+              reason: "ref_not_indexed",
+              error,
+            })
+            await emitWorkflowTelemetry(logClient, "warn", "akm.feedback.skipped", {
+              sessionID: context.sessionID,
+              toolName: "akm_feedback",
+              assetRef: ref,
+              outcome: "skipped",
+              reason: "ref not indexed",
+              directory: context.directory,
+            })
+            return JSON.stringify({ ok: true, skipped: true, reason: "ref_not_indexed", ref, sentiment })
+          }
+          return raw
+        }
         await emitWorkflowTelemetry(logClient, "info", "akm.feedback.recorded", {
           sessionID: context.sessionID,
           toolName: "akm_feedback",
@@ -2916,6 +2994,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               })
               return JSON.stringify({ ok: true, ref, shell: stdout.trim() })
             } catch (error: unknown) {
+              await writePluginLog(logClient, "error", "AKM vault load failed", {
+                subsystem: "vault",
+                toolName: "akm_vault",
+                action: "load",
+                ref,
+                error: formatCliError(error),
+              })
               return JSON.stringify({ ok: false, error: formatCliError(error) })
             }
           }
@@ -3023,6 +3108,15 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
                 })
                 return stdout
               } catch (error: unknown) {
+                await writePluginLog(logClient, "error", "AKM wiki stash failed", {
+                  subsystem: "wiki",
+                  toolName: "akm_wiki",
+                  action: "stash",
+                  name,
+                  source,
+                  as_slug,
+                  error: formatCliError(error),
+                })
                 return JSON.stringify({ ok: false, error: formatCliError(error) })
               }
             }
@@ -3130,6 +3224,12 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               })
               return JSON.stringify({ ok: true, template: stdout })
             } catch (error: unknown) {
+              await writePluginLog(logClient, "error", "AKM workflow template failed", {
+                subsystem: "workflow",
+                toolName: "akm_workflow",
+                action: "template",
+                error: formatCliError(error),
+              })
               return JSON.stringify({ ok: false, error: formatCliError(error) })
             }
           }
@@ -3212,15 +3312,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         return runCli(client as unknown as LogCapableClient, ["distill", ref], { toolName: "akm_distill" })
       },
     }),
-    akm_setup: tool({
-      description: "Detect installed agent CLIs (opencode, claude, codex, gemini, aider) and persist `agent.default`. Required once per machine before akm_reflect / akm_propose can shell out. Idempotent — pass force=true to re-run detection even when agent.default is already set.",
-      args: {
-        force: tool.schema.boolean().optional().describe("Re-run detection even when agent.default is already configured."),
-      },
-      async execute({ force }) {
-        const args = ["setup"]
-        if (force) args.push("--force")
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_setup" })
+    akm_init: tool({
+      description: "Initialize AKM's working stash directory and persist `stashDir` in config. This is the agent-safe initialization path; do not use interactive `akm setup` from tools.",
+      args: {},
+      async execute() {
+        return runCli(client as unknown as LogCapableClient, ["init"], { toolName: "akm_init" })
       },
     }),
     akm_help: tool({
@@ -3242,6 +3338,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             timeout: 30_000,
           }).toString().trim()
         } catch (error: unknown) {
+          await writePluginLog(logClient, "error", "AKM help command failed", {
+            subsystem: "help",
+            toolName: "akm_help",
+            command: cliCommand,
+            args: helpArgs,
+            error: formatCliError(error),
+          })
           return JSON.stringify({ ok: false, error: formatCliError(error) })
         }
         return JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-opencode",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "type": "module",
   "description": "OpenCode plugin for AKM v0.7.0 - search, show, and manage extension assets via the akm CLI, including vaults, wikis, workflows, the proposal queue, lesson assets, and reflect/propose/distill commands, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
   "keywords": [