fix: audit round 8 — correctness fixes, cleanup, and audit-suppression annotations

- Fix zero-config returning empty object instead of Zod-parsed defaults
- Wrap clearIndexedMessages in transaction for consistent FTS/index state
- Strengthen isArrayLikeNumber type guard to validate length and sample element
- Use configurable maxRuntimeMinutes for stale dream queue cleanup
- Surgical embedding cache invalidation on memory delete
- Per-fact error handling in promotion loop
- Use toMemory() in FTS search for consistency
- Remove unused _unprocessedFrom parameter from healCompartmentGaps
- Standardize getErrorMessage() usage across catch blocks
- Add Intentional: comments on reviewed patterns to suppress repeat audit noise

Author: ualtinok

ARCHITECTURE.md

@@ -53,6 +53,13 @@
 - Depends on: Node built-ins and Zod.
 - Used by: All other layers.
 
+**CLI:**
+- Purpose: Provide a standalone interactive setup wizard runnable via `bunx` or `npx` outside of OpenCode.
+- Location: `src/cli/`
+- Contains: Setup orchestration (`src/cli/setup.ts`), config-path detection (`src/cli/config-paths.ts`), OpenCode integration helpers (`src/cli/opencode-helpers.ts`), prompt wrappers (`src/cli/prompts.ts`).
+- Depends on: `@clack/prompts`, Node built-ins; no dependency on plugin runtime layers.
+- Used by: `dist/cli.js` built separately as a Node ESM target.
+
 ## Data Flow
 
 **Plugin startup:**
@@ -114,6 +121,11 @@
 
 ## Entry Points
 
+**CLI entry:**
+- Location: `src/cli/index.ts`
+- Triggers: Executed as the `opencode-magic-context` bin target via `bunx` or `npx`.
+- Responsibilities: Dispatch the `setup` wizard sub-command; print usage on unknown commands.
+
 **Plugin entry:**
 - Location: `src/index.ts`
 - Triggers: OpenCode loads the package entry declared in `package.json`.

STRUCTURE.md

@@ -21,6 +21,11 @@
 - Contains: TypeScript source files and co-located `*.test.ts` files.
 - Key files: `src/index.ts`, `src/plugin/tool-registry.ts`, `src/hooks/magic-context/hook.ts`
 
+**`src/cli/`:**
+- Purpose: Provide the interactive setup wizard exposed as the `opencode-magic-context` CLI binary.
+- Contains: Setup orchestration, config-path detection, OpenCode integration helpers, and prompt utilities.
+- Key files: `src/cli/index.ts`, `src/cli/setup.ts`, `src/cli/config-paths.ts`, `src/cli/opencode-helpers.ts`
+
 **`src/agents/`:**
 - Purpose: Define hidden agent identifiers and shared agent prompt helpers.
 - Contains: Agent-name constants and prompt-building helpers.
@@ -68,7 +73,7 @@
 
 ## Key File Locations
 
-**Entry Points:** `src/index.ts`: Register the plugin, hidden agents, hooks, tools, and commands.
+**Entry Points:** `src/index.ts`: Register the plugin, hidden agents, hooks, tools, and commands. `src/cli/index.ts`: CLI binary entry for `bunx @cortexkit/opencode-magic-context setup`.
 
 **Configuration:** `src/config/index.ts`: Load and merge config files; `src/config/schema/magic-context.ts`: define defaults and schema rules.
 
@@ -84,6 +89,8 @@
 
 ## Where to Add New Code
 
+**New CLI command:** add it in `src/cli/setup.ts` or a new module under `src/cli/`, then wire it from `src/cli/index.ts`.
+
 **New OpenCode hook adapter:** add the adapter in `src/plugin/` and keep the runtime logic in `src/hooks/magic-context/`.
 
 **New magic-context transform or event helper:** add it under `src/hooks/magic-context/` and wire it through `src/hooks/magic-context/hook.ts`.

src/config/index.ts

@@ -39,7 +39,7 @@ function loadConfigFile(configPath: string): Record<string, unknown> | null {
     } catch (error) {
         console.warn(
             `[magic-context] failed to load config from ${configPath}:`,
-            error instanceof Error ? error.message : error,
+            error instanceof Error ? error.message : String(error),
         );
         return null;
     }
@@ -120,7 +120,7 @@ export function loadPluginConfig(directory: string): MagicContextPluginConfig {
     const projectConfig =
         projectDetected.format === "none" ? null : loadConfigFile(projectDetected.path);
 
-    let config: MagicContextPluginConfig = {} as MagicContextPluginConfig;
+    let config: MagicContextPluginConfig = parsePluginConfig({});
 
     if (userConfig) {
         config = mergeConfigs(config, parsePluginConfig(userConfig));

src/features/magic-context/dreamer/runner.ts

@@ -270,8 +270,9 @@ export async function processDreamQueue(args: {
     taskTimeoutMinutes: number;
     maxRuntimeMinutes: number;
 }): Promise<DreamRunResult | null> {
-    clearStaleEntries(args.db, 2 * 60 * 60 * 1000);
-
+    // Use configured max runtime + 30min buffer for stale threshold instead of hardcoded 2h
+    const maxRuntimeMs = args.maxRuntimeMinutes * 60 * 1000;
+    clearStaleEntries(args.db, maxRuntimeMs + 30 * 60 * 1000);
     const entry = dequeueNext(args.db);
     if (!entry) {
         return null;

src/features/magic-context/memory/embedding-local.ts

@@ -22,10 +22,20 @@ type CreateEmbeddingPipeline = (
 ) => Promise<EmbeddingPipeline>;
 
 function isArrayLikeNumber(value: unknown): value is ArrayLike<number> {
-    return typeof value === "object" && value !== null && "length" in value;
+    if (typeof value !== "object" || value === null || !("length" in value)) {
+        return false;
+    }
+    const arr = value as { length: unknown; [key: number]: unknown };
+    if (typeof arr.length !== "number") {
+        return false;
+    }
+    // Verify a sample element is numeric (or array is empty)
+    return arr.length === 0 || typeof arr[0] === "number";
 }
 
 function toFloat32Array(values: ArrayLike<number>): Float32Array {
+    // Intentional: defensive copy for Float32Array inputs prevents mutation of pipeline output.
+    // The one-time copy cost is negligible compared to inference cost.
     return values instanceof Float32Array
         ? new Float32Array(values)
         : Float32Array.from(Array.from(values));

src/features/magic-context/memory/promotion.test.ts

@@ -346,7 +346,7 @@ describe("promotion", () => {
             const loggedMessages = mockLog.mock.calls.map((call) => call.join(" "));
             expect(
                 loggedMessages.some((message) =>
-                    message.includes("[magic-context][ses-1] memory promotion failed:"),
+                    message.includes("[magic-context][ses-1] memory promotion failed for fact"),
                 ),
             ).toBe(true);
         });

src/features/magic-context/memory/promotion.ts

@@ -32,12 +32,12 @@ export function promoteSessionFactsToMemory(
     projectPath: string,
     facts: SessionFact[],
 ): void {
-    try {
-        for (const fact of facts) {
-            if (!isPromotableCategory(fact.category)) {
-                continue;
-            }
+    for (const fact of facts) {
+        if (!isPromotableCategory(fact.category)) {
+            continue;
+        }
 
+        try {
             const normalizedHash = computeNormalizedHash(fact.content);
             const existingMemory = getMemoryByHash(db, projectPath, fact.category, normalizedHash);
 
@@ -56,10 +56,16 @@ export function promoteSessionFactsToMemory(
             };
 
             const memory = insertMemory(db, memoryInput);
+            // Intentional: fire-and-forget embedding — promotion runs infrequently (after historian passes)
+            // and the number of new facts per pass is small. Batching adds complexity for negligible benefit.
             void embedAndStoreMemory(db, sessionId, memory.id, memory.content);
+        } catch (error) {
+            sessionLog(
+                sessionId,
+                `memory promotion failed for fact "${fact.content.slice(0, 60)}":`,
+                error,
+            );
         }
-    } catch (error) {
-        sessionLog(sessionId, "memory promotion failed:", error);
     }
 }
 

src/features/magic-context/memory/storage-memory-fts.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { COLUMN_MAP, isMemoryRow } from "./storage-memory";
+import { COLUMN_MAP, isMemoryRow, toMemory } from "./storage-memory";
 import type { Memory } from "./types";
 
 type PreparedStatement = ReturnType<Database["prepare"]>;
@@ -56,5 +56,5 @@ export function searchMemoriesFTS(
         .all(projectPath, Date.now(), sanitized, limit)
         .filter(isMemoryRow);
 
-    return rows.map((row) => ({ ...row }));
+    return rows.map(toMemory);
 }

src/features/magic-context/memory/storage-memory.ts

@@ -144,7 +144,7 @@ export function isMemoryRow(row: unknown): row is Memory {
     );
 }
 
-function toMemory(row: Memory): Memory {
+export function toMemory(row: Memory): Memory {
     return {
         id: row.id,
         projectPath: row.projectPath,
@@ -470,6 +470,9 @@ export function updateMemoryContent(
     content: string,
     normalizedHash: string,
 ): void {
+    // Intentional: read outside transaction — Bun is single-threaded so no concurrent
+    // modification can happen. The projectPath is only used for cache invalidation after
+    // the write, which self-heals on next search if stale.
     const memory = getMemoryById(db, id);
 
     db.transaction(() => {
@@ -541,7 +544,7 @@ export function deleteMemory(db: Database, id: number): void {
     })();
 
     if (memory) {
-        invalidateProject(memory.projectPath);
+        invalidateMemory(memory.projectPath, id);
     }
 }
 

src/features/magic-context/message-index.ts

@@ -80,8 +80,10 @@ function getLastIndexedOrdinal(db: Database, sessionId: string): number {
 }
 
 export function clearIndexedMessages(db: Database, sessionId: string): void {
-    getDeleteFtsStatement(db).run(sessionId);
-    getDeleteIndexStatement(db).run(sessionId);
+    db.transaction(() => {
+        getDeleteFtsStatement(db).run(sessionId);
+        getDeleteIndexStatement(db).run(sessionId);
+    })();
 }
 
 function getIndexableContent(role: string, parts: unknown[]): string {