gnosys 5.14.0 → 5.15.2

package/README.md

@@ -71,8 +71,8 @@ This package installs two binaries:
 | `gnosys_read` | Read a specific memory. |
 | `gnosys_search` | Search memories by keyword across all stores. |
 | `gnosys_list` | List memories across all stores, optionally filtered by category, tag, or store layer. |
-| `gnosys_add` | Add a new memory. |
-| `gnosys_add_structured` | Add a memory with structured input (no LLM needed). |
+| `gnosys_add_structured` | **Preferred for LLM agents.** Add a memory with structured fields you supply (title, category, tags, content) — makes no server-side LLM call. |
+| `gnosys_add` | Add a memory from raw text; the server's LLM structures it. For non-agent callers (scripts, cron) — agents should use `gnosys_add_structured`. |
 | `gnosys_tags` | List all tags in the registry, grouped by category. |
 | `gnosys_tags_add` | Add a new tag to the registry. |
 | `gnosys_reinforce` | Signal whether a memory was useful. |

package/dist/cli.js

@@ -1097,6 +1097,12 @@ program
         console.error(`\nCould not write upgrade marker: ${err instanceof Error ? err.message : err}`);
         console.error(`Running MCP servers will need to be restarted manually.`);
     }
+    // v5.15: a Node upgrade moves the node path hardcoded in the dream
+    // LaunchAgent plist, silently killing the scheduler. Repair it here.
+    const { repairDreamLaunchAgentAfterUpgrade } = await import("./lib/dreamLaunchd.js");
+    const dreamRepairLine = await repairDreamLaunchAgentAfterUpgrade();
+    if (dreamRepairLine)
+        console.log(`\n${dreamRepairLine}`);
     if (opts.sync === false || opts.yes) {
         console.log(`\nDone. Run 'gnosys setup sync-projects' when you're ready to refresh registered projects.`);
         return;

package/dist/index.js

@@ -624,7 +624,7 @@ regTool("gnosys_list", "List memories across all stores, optionally filtered by
     }
 });
 // ─── Tool: gnosys_add ────────────────────────────────────────────────────
-regTool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structures it into an atomic memory. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
+regTool("gnosys_add", "Add a new memory from raw text — the server's LLM structures it into an atomic memory. For non-agent callers (scripts, cron); if you are an LLM agent, use gnosys_add_structured instead to avoid a redundant server-side LLM call. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
     input: z
         .string()
         .describe("Raw text input. Can be a decision, concept, fact, observation, or any knowledge."),
@@ -738,7 +738,7 @@ regTool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structures
     }
 });
 // ─── Tool: gnosys_add_structured ─────────────────────────────────────────
-regTool("gnosys_add_structured", "Add a memory with structured input (no LLM needed). Writes to the project store by default. Use store='global' to explicitly write to shared org knowledge.", {
+regTool("gnosys_add_structured", "Preferred for LLM agents: add a memory with structured fields you supply (title, category, tags, content) — makes no server-side LLM call. Writes to the project store by default. Use store='global' to explicitly write to shared org knowledge.", {
     title: z.string().describe("Memory title"),
     category: z.string().describe("Category directory name"),
     tags: z
@@ -1703,7 +1703,8 @@ regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gn
             skipExisting,
             limit,
             offset,
-            concurrency,
+            // v5.15: explicit param wins; otherwise config importConcurrency.
+            concurrency: concurrency ?? ctx.config?.importConcurrency,
             batchCommit: true,
         });
         // Reindex after import

package/dist/lib/ask.js

@@ -289,7 +289,11 @@ export class GnosysAsk {
             }
             return usedArchiveIds;
         }
-        catch {
+        catch (err) {
+            // Degrade gracefully, but leave a trace on stderr — a hard dearchive
+            // failure previously looked identical to "no archive hits"
+            // (sprint 2026-07-02).
+            console.error(`gnosys: dearchive failed: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
     }

package/dist/lib/askCommand.js

@@ -132,7 +132,10 @@ export async function runAskCommand(getResolver, question, opts) {
             const writeTarget = resolver.getWriteTarget();
             if (writeTarget) {
                 const { GnosysMaintenanceEngine } = await import("./maintenance.js");
-                await GnosysMaintenanceEngine.reinforceBatch(writeTarget.store, result.sources.map((s) => s.relativePath)).catch(() => { });
+                await GnosysMaintenanceEngine.reinforceBatch(writeTarget.store, result.sources.map((s) => s.relativePath)).catch((err) => {
+                    // Best-effort, but don't be fully silent (sprint 2026-07-02).
+                    console.error(`gnosys: reinforcement skipped: ${err instanceof Error ? err.message : String(err)}`);
+                });
             }
         }
     }

package/dist/lib/chat/llmTurn.d.ts

@@ -42,6 +42,15 @@ export interface LLMTurnResult {
         result: string;
     }>;
 }
+/**
+ * Build the system prompt for a chat turn.
+ *
+ * v5.15: wires two previously-unread config knobs —
+ * `chat.systemPromptPrefix` (prepended before the base prompt) and
+ * `chat.toolsEnabled` (false omits the gnosys-tool addendum entirely).
+ * Exported for tests.
+ */
+export declare function composeSystemPrompt(config: GnosysConfig, recalled: RecalledMemory[] | undefined): string;
 /**
  * Run a single turn against the LLM. Loops if the assistant emits
  * gnosys-tool fences: each tool is executed in-process, the result is

package/dist/lib/chat/llmTurn.js

@@ -12,9 +12,23 @@ import { CHOOSE_SYSTEM_PROMPT_ADDENDUM } from "./choose.js";
 import { buildToolsSystemPrompt, findTool } from "./tools.js";
 import { extractToolFences } from "./toolFence.js";
 const BASE_SYSTEM_PROMPT = `You are an assistant inside the Gnosys terminal chat — a memory-aware REPL. The user has persistent memory across sessions; relevant memories are injected as <memory id="..."> blocks before their question. Cite memory IDs in square brackets like [deci-037] when you use them. Be concise and direct. Markdown renders.${CHOOSE_SYSTEM_PROMPT_ADDENDUM}`;
-function composeSystemPrompt(recalled) {
-    const toolsAddendum = buildToolsSystemPrompt();
-    const base = `${BASE_SYSTEM_PROMPT}\n${toolsAddendum}`;
+/**
+ * Build the system prompt for a chat turn.
+ *
+ * v5.15: wires two previously-unread config knobs —
+ * `chat.systemPromptPrefix` (prepended before the base prompt) and
+ * `chat.toolsEnabled` (false omits the gnosys-tool addendum entirely).
+ * Exported for tests.
+ */
+export function composeSystemPrompt(config, recalled) {
+    const toolsEnabled = config.chat?.toolsEnabled !== false;
+    let base = toolsEnabled
+        ? `${BASE_SYSTEM_PROMPT}\n${buildToolsSystemPrompt()}`
+        : BASE_SYSTEM_PROMPT;
+    const prefix = config.chat?.systemPromptPrefix;
+    if (typeof prefix === "string" && prefix.trim().length > 0) {
+        base = `${prefix.trim()}\n\n${base}`;
+    }
     if (!recalled || recalled.length === 0)
         return base;
     return `${base}\n\n${formatRecallForPrompt(recalled)}`;
@@ -47,8 +61,11 @@ export async function runTurn(config, opts) {
     // falls back to defaultProvider when no chat override is set, so existing
     // installs keep working without a chat-specific config.
     const provider = getLLMProvider(config, "chat");
-    const system = composeSystemPrompt(opts.recalled);
-    const maxIterations = opts.maxToolIterations ?? 4;
+    const system = composeSystemPrompt(config, opts.recalled);
+    // v5.15: when chat.toolsEnabled === false the first response is final —
+    // no tool-fence execution loop.
+    const toolsEnabled = config.chat?.toolsEnabled !== false;
+    const maxIterations = toolsEnabled ? (opts.maxToolIterations ?? 4) : 1;
     const toolCalls = [];
     let toolPreamble;
     let combinedText = "";
@@ -64,7 +81,7 @@ export async function runTurn(config, opts) {
         combinedText += (combinedText ? "\n\n" : "") + chunk;
         // Look for tool fences; if none, this iteration's chunk IS the answer.
         const extraction = extractToolFences(chunk);
-        if (!extraction || extraction.calls.length === 0) {
+        if (!toolsEnabled || !extraction || extraction.calls.length === 0) {
             break;
         }
         // Run each tool, accumulate results into the next prompt as a system block

package/dist/lib/config.d.ts

@@ -183,7 +183,6 @@ export declare const GnosysConfigSchema: z.ZodObject<{
         openai: "openai";
     }>>;
     defaultModel: z.ZodOptional<z.ZodString>;
-    bulkIngestionBatchSize: z.ZodDefault<z.ZodNumber>;
     importConcurrency: z.ZodDefault<z.ZodNumber>;
     autoCommit: z.ZodDefault<z.ZodBoolean>;
     llmRetryAttempts: z.ZodDefault<z.ZodNumber>;
@@ -241,7 +240,6 @@ export declare const GnosysConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     chat: z.ZodDefault<z.ZodObject<{
         toolsEnabled: z.ZodDefault<z.ZodBoolean>;
-        autoSummarizeAfterTurns: z.ZodDefault<z.ZodNumber>;
         systemPromptPrefix: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     multimodal: z.ZodDefault<z.ZodObject<{

package/dist/lib/config.js

@@ -137,9 +137,6 @@ const RecallConfigSchema = z.object({
 const ChatConfigSchema = z.object({
     /** Allow LLM to call gnosys tools via gnosys-tool fences (default: true). */
     toolsEnabled: z.boolean().default(true),
-    /** Suggest /save-turn after N consecutive turns where no memory was written.
-     *  0 disables the nudge. Heuristic only — never writes without consent. */
-    autoSummarizeAfterTurns: z.number().int().min(0).default(0),
     /** Prepended to the chat system prompt. Use for persona / style / domain hints. */
     systemPromptPrefix: z.string().default(""),
 });
@@ -210,8 +207,6 @@ export const GnosysConfigSchema = z.object({
         .optional(),
     /** @deprecated Use llm.anthropic.model or llm.ollama.model instead */
     defaultModel: z.string().optional(),
-    /** Max records per batch commit during bulk import */
-    bulkIngestionBatchSize: z.number().int().min(1).max(10000).default(500),
     /** Parallel LLM calls during import */
     importConcurrency: z.number().int().min(1).max(20).default(5),
     /** Enable auto-commit on every write (disable for manual git) */
@@ -259,7 +254,6 @@ export const GnosysConfigSchema = z.object({
     /** Chat TUI — interactive chat configuration (v5.8.0) */
     chat: ChatConfigSchema.default({
         toolsEnabled: true,
-        autoSummarizeAfterTurns: 0,
         systemPromptPrefix: "",
     }),
     /** Multimodal ingestion — PDF, audio, image, video processing */
@@ -483,6 +477,30 @@ function deepMergeConfig(base, override) {
     }
     return result;
 }
+// ─── Removed-knob deprecation warnings (v5.15) ──────────────────────────
+//
+// These knobs were documented but never read by any code ("settings that
+// lie"), so v5.15 removed them from the schema. Zod strips unknown keys on
+// parse, so old config files keep loading — but warn once per process (on
+// stderr only; MCP serve stdout must stay clean for JSON-RPC).
+const warnedRemovedKeys = new Set();
+function warnRemovedConfigKeys(raw) {
+    const found = [];
+    if ("bulkIngestionBatchSize" in raw)
+        found.push("bulkIngestionBatchSize");
+    const chat = raw.chat;
+    if (typeof chat === "object" &&
+        chat !== null &&
+        "autoSummarizeAfterTurns" in chat) {
+        found.push("chat.autoSummarizeAfterTurns");
+    }
+    for (const key of found) {
+        if (warnedRemovedKeys.has(key))
+            continue;
+        warnedRemovedKeys.add(key);
+        console.error(`gnosys: config option "${key}" was removed in v5.15 and is ignored`);
+    }
+}
 export async function loadConfig(storePath) {
     const configPath = path.join(storePath, "gnosys.json");
     const globalPath = path.join(getGnosysHome(), "gnosys.json");
@@ -510,6 +528,7 @@ export async function loadConfig(storePath) {
         if (raw === null) {
             return DEFAULT_CONFIG;
         }
+        warnRemovedConfigKeys(raw);
         const migrated = migrateConfig(raw);
         const parsed = GnosysConfigSchema.parse(migrated);
         return applyDreamProviderInheritance(parsed, migrated);
@@ -579,7 +598,6 @@ export function generateConfigTemplate() {
             },
         },
         taskModels: {},
-        bulkIngestionBatchSize: 500,
         importConcurrency: 5,
         autoCommit: true,
         llmRetryAttempts: 3,
@@ -608,7 +626,6 @@ export function generateConfigTemplate() {
         },
         chat: {
             toolsEnabled: true,
-            autoSummarizeAfterTurns: 0,
             systemPromptPrefix: "",
         },
     }, null, 2);

package/dist/lib/dreamLaunchd.d.ts

@@ -1,2 +1,67 @@
+export interface LaunchctlResult {
+    ok: boolean;
+    message: string;
+}
+/** Pure helper: argv for loading a LaunchAgent plist. Exported for tests. */
+export declare function launchctlLoadArgs(plistFile: string): string[];
+/** Pure helper: argv for unloading a LaunchAgent plist. Exported for tests. */
+export declare function launchctlUnloadArgs(plistFile: string): string[];
+/**
+ * Pure helper: interpret a launchctl load failure. "Already loaded" is a
+ * success for our purposes (the agent is active). Exported for tests.
+ */
+export declare function interpretLaunchctlLoadError(stderr: string): LaunchctlResult;
+/**
+ * Best-effort `launchctl load` of the dream LaunchAgent so scheduled runs
+ * start immediately instead of waiting for the next login. (v5.14.x sprint,
+ * pre-approved.) Never throws.
+ */
+export declare function loadDreamLaunchAgent(plistFile: string): LaunchctlResult;
+/**
+ * Best-effort `launchctl unload` before removing the plist, so disabling
+ * Dream Mode deactivates the schedule immediately. Never throws.
+ */
+export declare function unloadDreamLaunchAgent(plistFile: string): LaunchctlResult;
 export declare function installDreamLaunchAgent(): string | null;
+/**
+ * Pure helper: extract the node and cli paths from a dream LaunchAgent
+ * plist body. Template shape (installDreamLaunchAgent): the first
+ * `<string>` is the Label, the second is the node binary path, the third
+ * is the cli path. Exported for tests.
+ */
+export declare function parseDreamPlistPaths(body: string): {
+    nodePath?: string;
+    cliPath?: string;
+};
+export interface DreamLaunchAgentHealth {
+    installed: boolean;
+    loaded: boolean;
+    nodeExists: boolean;
+    cliExists: boolean;
+    healthy: boolean;
+    problems: string[];
+    plistFile: string | null;
+}
+/**
+ * Health-check the dream LaunchAgent. The plist hardcodes absolute node +
+ * cli paths (e.g. ~/.nvm/versions/node/vX.Y.Z/bin/node), so a Node upgrade
+ * silently kills the scheduler — this detects that. Never throws.
+ */
+export declare function checkDreamLaunchAgent(): DreamLaunchAgentHealth;
+/**
+ * Repair the dream LaunchAgent: rewrite the plist with the current
+ * process's node + cli paths, then reload it. Best-effort — never throws.
+ */
+export declare function repairDreamLaunchAgent(): {
+    ok: boolean;
+    message: string;
+};
+/**
+ * Post-upgrade hook: when Dream Mode is enabled and the LaunchAgent is
+ * installed but unhealthy (typically because a Node upgrade moved the
+ * hardcoded node path), repair it. Returns a printable status line, or
+ * null when nothing applies (non-darwin, dream disabled, agent healthy
+ * or not installed). Never throws.
+ */
+export declare function repairDreamLaunchAgentAfterUpgrade(): Promise<string | null>;
 export declare function uninstallDreamLaunchAgent(): string | null;

package/dist/lib/dreamLaunchd.js

@@ -1,7 +1,73 @@
+import { execFileSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path from "path";
 const LABEL = "com.gnosys.dream";
+/** Pure helper: argv for loading a LaunchAgent plist. Exported for tests. */
+export function launchctlLoadArgs(plistFile) {
+    return ["load", "-w", plistFile];
+}
+/** Pure helper: argv for unloading a LaunchAgent plist. Exported for tests. */
+export function launchctlUnloadArgs(plistFile) {
+    return ["unload", plistFile];
+}
+/**
+ * Pure helper: interpret a launchctl load failure. "Already loaded" is a
+ * success for our purposes (the agent is active). Exported for tests.
+ */
+export function interpretLaunchctlLoadError(stderr) {
+    const text = stderr.trim();
+    if (/already loaded|service already loaded|Load failed: 5/i.test(text)) {
+        return { ok: true, message: "launchd agent already loaded" };
+    }
+    return {
+        ok: false,
+        message: `launchctl load failed${text ? `: ${text}` : ""} — the agent will load at next login`,
+    };
+}
+/**
+ * Best-effort `launchctl load` of the dream LaunchAgent so scheduled runs
+ * start immediately instead of waiting for the next login. (v5.14.x sprint,
+ * pre-approved.) Never throws.
+ */
+export function loadDreamLaunchAgent(plistFile) {
+    if (process.platform !== "darwin")
+        return { ok: false, message: "launchctl unavailable (not macOS)" };
+    try {
+        execFileSync("launchctl", launchctlLoadArgs(plistFile), {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+        });
+        return { ok: true, message: "launchd agent loaded — scheduled dream runs are active now" };
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err && err.stderr
+            ? String(err.stderr)
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return interpretLaunchctlLoadError(stderr);
+    }
+}
+/**
+ * Best-effort `launchctl unload` before removing the plist, so disabling
+ * Dream Mode deactivates the schedule immediately. Never throws.
+ */
+export function unloadDreamLaunchAgent(plistFile) {
+    if (process.platform !== "darwin")
+        return { ok: false, message: "launchctl unavailable (not macOS)" };
+    try {
+        execFileSync("launchctl", launchctlUnloadArgs(plistFile), {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+        });
+        return { ok: true, message: "launchd agent unloaded" };
+    }
+    catch {
+        // Not loaded (or launchctl unavailable) — nothing to deactivate.
+        return { ok: true, message: "launchd agent was not loaded" };
+    }
+}
 function plistPath() {
     return path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 }
@@ -58,10 +124,151 @@ export function installDreamLaunchAgent() {
     fs.writeFileSync(file, body, "utf8");
     return file;
 }
+function xmlUnescape(value) {
+    return value
+        .replace(/"/g, '"')
+        .replace(/>/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * Pure helper: extract the node and cli paths from a dream LaunchAgent
+ * plist body. Template shape (installDreamLaunchAgent): the first
+ * `<string>` is the Label, the second is the node binary path, the third
+ * is the cli path. Exported for tests.
+ */
+export function parseDreamPlistPaths(body) {
+    const strings = [...body.matchAll(/<string>([^<]*)<\/string>/g)].map((m) => xmlUnescape(m[1]));
+    return {
+        nodePath: strings.length > 1 ? strings[1] : undefined,
+        cliPath: strings.length > 2 ? strings[2] : undefined,
+    };
+}
+/**
+ * Health-check the dream LaunchAgent. The plist hardcodes absolute node +
+ * cli paths (e.g. ~/.nvm/versions/node/vX.Y.Z/bin/node), so a Node upgrade
+ * silently kills the scheduler — this detects that. Never throws.
+ */
+export function checkDreamLaunchAgent() {
+    if (process.platform !== "darwin") {
+        return {
+            installed: false,
+            loaded: false,
+            nodeExists: false,
+            cliExists: false,
+            healthy: false,
+            problems: ["launchd unavailable (not macOS)"],
+            plistFile: null,
+        };
+    }
+    const file = plistPath();
+    if (!fs.existsSync(file)) {
+        return {
+            installed: false,
+            loaded: false,
+            nodeExists: false,
+            cliExists: false,
+            healthy: false,
+            problems: ["launchd agent not installed"],
+            plistFile: file,
+        };
+    }
+    const problems = [];
+    let nodeExists = false;
+    let cliExists = false;
+    try {
+        const body = fs.readFileSync(file, "utf8");
+        const { nodePath, cliPath } = parseDreamPlistPaths(body);
+        nodeExists = nodePath !== undefined && fs.existsSync(nodePath);
+        if (!nodeExists) {
+            problems.push(`node binary missing at ${nodePath ?? "(unknown)"} — a Node upgrade likely moved it; run repair to rewrite the agent`);
+        }
+        // "gnosys" (bare command) counts as existing — resolved via PATH.
+        cliExists =
+            cliPath !== undefined && (cliPath === "gnosys" || fs.existsSync(cliPath));
+        if (!cliExists) {
+            problems.push(`gnosys cli missing at ${cliPath ?? "(unknown)"}`);
+        }
+    }
+    catch (err) {
+        problems.push(`could not read plist: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let loaded = false;
+    try {
+        execFileSync("launchctl", ["list", LABEL], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 10_000,
+        });
+        loaded = true;
+    }
+    catch {
+        problems.push("launchd agent not loaded");
+    }
+    return {
+        installed: true,
+        loaded,
+        nodeExists,
+        cliExists,
+        healthy: loaded && nodeExists && cliExists,
+        problems,
+        plistFile: file,
+    };
+}
+/**
+ * Repair the dream LaunchAgent: rewrite the plist with the current
+ * process's node + cli paths, then reload it. Best-effort — never throws.
+ */
+export function repairDreamLaunchAgent() {
+    const file = installDreamLaunchAgent();
+    if (!file) {
+        return { ok: false, message: "launchd unavailable (not macOS)" };
+    }
+    unloadDreamLaunchAgent(file);
+    const load = loadDreamLaunchAgent(file);
+    if (!load.ok) {
+        return {
+            ok: false,
+            message: `agent reinstalled but reload failed: ${load.message}`,
+        };
+    }
+    return { ok: true, message: "dream launchd agent repaired and reloaded" };
+}
+/**
+ * Post-upgrade hook: when Dream Mode is enabled and the LaunchAgent is
+ * installed but unhealthy (typically because a Node upgrade moved the
+ * hardcoded node path), repair it. Returns a printable status line, or
+ * null when nothing applies (non-darwin, dream disabled, agent healthy
+ * or not installed). Never throws.
+ */
+export async function repairDreamLaunchAgentAfterUpgrade() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const { loadConfig } = await import("./config.js");
+        const { getGnosysHome } = await import("./paths.js");
+        const config = await loadConfig(getGnosysHome());
+        if (!config.dream?.enabled)
+            return null;
+        const health = checkDreamLaunchAgent();
+        if (!health.installed || health.healthy)
+            return null;
+        const repair = repairDreamLaunchAgent();
+        return repair.ok
+            ? "✓ dream launchd agent repaired (node path had changed)"
+            : `⚠ dream launchd agent unhealthy and repair failed: ${repair.message}`;
+    }
+    catch {
+        return null;
+    }
+}
 export function uninstallDreamLaunchAgent() {
     if (process.platform !== "darwin")
         return null;
     const file = plistPath();
+    // Unload before unlinking — launchctl needs the plist on disk to resolve
+    // the label, and this deactivates the schedule immediately. Best-effort.
+    if (fs.existsSync(file))
+        unloadDreamLaunchAgent(file);
     try {
         fs.unlinkSync(file);
     }

package/dist/lib/embeddings.js

@@ -35,8 +35,10 @@ export class GnosysEmbeddings {
         const cacheDir = process.env.GNOSYS_CACHE_DIR ||
             path.join(process.env.HOME || process.env.USERPROFILE || "/tmp", ".cache", "gnosys");
         await fs.mkdir(cacheDir, { recursive: true });
-        // HF_HOME is the canonical env var in @huggingface/transformers v3+;
-        // keep TRANSFORMERS_CACHE set too for any tooling that still reads it.
+        // NOTE: @huggingface/transformers does NOT honor HF_HOME/TRANSFORMERS_CACHE
+        // for its Node file cache (that's the Python huggingface_hub convention).
+        // It caches under its own `env.cacheDir`, which we set below after import.
+        // We still export the env vars for any adjacent tooling that reads them.
         process.env.HF_HOME = cacheDir;
         process.env.TRANSFORMERS_CACHE = cacheDir;
         // Dynamic import — keeps @huggingface/transformers out of the main bundle.
@@ -45,13 +47,22 @@ export class GnosysEmbeddings {
         // Use `any` here so `tsc` succeeds even when the optional dep is not installed
         // (CI network-share-simulation job, fresh checkouts, etc.). The real type
         // is only needed at runtime when the package is present.
-        let pipeline;
+        // `any`: the optional dep may be absent at type-check time (see note above).
+        let transformers;
         try {
-            ({ pipeline } = await import("@huggingface/transformers"));
+            transformers = await import("@huggingface/transformers");
         }
         catch {
             throw new Error("Local embeddings require @huggingface/transformers. Install it with: npm install @huggingface/transformers");
         }
+        // `env.cacheDir` is the actual knob transformers.js uses for its on-disk
+        // model cache. Without it the model lands in the package's own
+        // node_modules/.cache (wiped on reinstall) and GNOSYS_CACHE_DIR is silently
+        // ignored — it does NOT honor HF_HOME/TRANSFORMERS_CACHE. Access by property
+        // (not destructuring) so a mocked module without `env` doesn't throw.
+        if (transformers.env)
+            transformers.env.cacheDir = cacheDir;
+        const pipeline = transformers.pipeline;
         this.pipeline = (await pipeline("feature-extraction", MODEL_NAME, {
             dtype: "q8",
         }));

package/dist/lib/hybridSearchCommand.js

@@ -92,7 +92,10 @@ export async function runHybridSearchCommand(getResolver, query, opts) {
         const writeTarget = resolver.getWriteTarget();
         if (writeTarget) {
             const { GnosysMaintenanceEngine } = await import("./maintenance.js");
-            await GnosysMaintenanceEngine.reinforceBatch(writeTarget.store, results.map((r) => r.relativePath)).catch(() => { });
+            await GnosysMaintenanceEngine.reinforceBatch(writeTarget.store, results.map((r) => r.relativePath)).catch((err) => {
+                // Best-effort, but don't be fully silent (sprint 2026-07-02).
+                console.error(`gnosys: reinforcement skipped: ${err instanceof Error ? err.message : String(err)}`);
+            });
         }
     }
     search.close();

package/dist/lib/importCommand.js

@@ -33,7 +33,11 @@ export async function runImportCommand(getResolver, fileOrUrl, opts) {
     const ingestion = new GnosysIngestion(writeTarget.store, tagRegistry);
     const format = opts.format;
     const mode = opts.mode;
-    const concurrency = opts.concurrency || 5;
+    // v5.15: --concurrency CLI flag wins; otherwise the config's
+    // importConcurrency (schema default 5) applies.
+    const { loadConfig } = await import("./config.js");
+    const config = await loadConfig(writeTarget.store.getStorePath());
+    const concurrency = opts.concurrency || config.importConcurrency;
     // Show estimate for LLM mode
     if (mode === "llm") {
         console.error(`Mode: LLM (concurrency: ${concurrency})`);

package/dist/lib/interactiveGuard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Guard for interactive prompt flows (v5.14.x sprint, pre-approved).
+ *
+ * Interactive setup flows crash with ERR_USE_AFTER_CLOSE when stdin is
+ * closed (e.g. `gnosys setup dream` run non-interactively from a script
+ * or CI). Instead of a stack trace, print a friendly one-line error and
+ * exit 1.
+ */
+/** Returns true when stdin can host an interactive prompt session. */
+export declare function stdinIsInteractive(): boolean;
+/** Human-readable message for a blocked interactive flow. */
+export declare function nonInteractiveMessage(flow: string): string;
+/**
+ * Exit with a friendly one-liner when stdin is not a TTY.
+ * Call at the entry of interactive prompt flows, before any readline use.
+ */
+export declare function guardInteractiveStdin(flow: string): void;

package/dist/lib/interactiveGuard.js

@@ -0,0 +1,26 @@
+/**
+ * Guard for interactive prompt flows (v5.14.x sprint, pre-approved).
+ *
+ * Interactive setup flows crash with ERR_USE_AFTER_CLOSE when stdin is
+ * closed (e.g. `gnosys setup dream` run non-interactively from a script
+ * or CI). Instead of a stack trace, print a friendly one-line error and
+ * exit 1.
+ */
+/** Returns true when stdin can host an interactive prompt session. */
+export function stdinIsInteractive() {
+    return Boolean(process.stdin.isTTY);
+}
+/** Human-readable message for a blocked interactive flow. */
+export function nonInteractiveMessage(flow) {
+    return `gnosys ${flow} is interactive and requires a terminal (stdin is not a TTY). Re-run from an interactive shell.`;
+}
+/**
+ * Exit with a friendly one-liner when stdin is not a TTY.
+ * Call at the entry of interactive prompt flows, before any readline use.
+ */
+export function guardInteractiveStdin(flow) {
+    if (stdinIsInteractive())
+        return;
+    console.error(nonInteractiveMessage(flow));
+    process.exit(1);
+}

package/dist/lib/rulesGen.js

@@ -35,7 +35,8 @@ This project uses **Gnosys** for persistent memory via MCP. Gnosys uses a centra
 
 ### Write automatically
 
-- When user says "remember", "memorize", "save this", "note this down", "don't forget" — call \`gnosys_add\`
+- **Always write with \`gnosys_add_structured\`** — you are an LLM, so structure the memory yourself (title, category, tags, content, relevance) and pass the explicit fields. Do NOT use the freeform \`gnosys_add\`: it makes the Gnosys server run a *second, redundant* LLM call to structure your text and adds an external provider-key dependency that can fail silently. \`gnosys_add_structured\` makes no server-side model call. (Freeform \`gnosys_add\` exists only for non-agent callers — cron jobs, scripts — that cannot structure text themselves.)
+- When user says "remember", "memorize", "save this", "note this down", "don't forget" — call \`gnosys_add_structured\`
 - When user states a decision or preference (even casually) — commit to \`decisions\` category
 - When user provides a spec or plan — commit BEFORE starting work
 - After significant implementation — commit findings and gotchas
@@ -47,7 +48,7 @@ This project uses **Gnosys** for persistent memory via MCP. Gnosys uses a centra
 |--------|------|
 | Find memories | \`gnosys_discover\` (metadata) → \`gnosys_read\` (content) |
 | Search | \`gnosys_hybrid_search\` (best), \`gnosys_federated_search\` (cross-project), \`gnosys_search\` (keyword), \`gnosys_ask\` (Q&A) |
-| Write | \`gnosys_add\` (freeform), \`gnosys_add_structured\` (explicit fields) |
+| Write | \`gnosys_add_structured\` (explicit fields — **always use this as an agent**; no server-side LLM call). \`gnosys_add\` (freeform) is for non-agent callers only. |
 | Update | \`gnosys_update\`, \`gnosys_reinforce\` (useful/not_relevant/outdated) |
 | Browse | \`gnosys_list\`, \`gnosys_lens\` (filtered), \`gnosys_tags\`, \`gnosys_graph\` |
 | Maintain | \`gnosys_maintain\`, \`gnosys_stale\`, \`gnosys_history\`, \`gnosys_dashboard\` |
@@ -63,7 +64,11 @@ This project uses **Gnosys** for persistent memory via MCP. Gnosys uses a centra
 
 ### Categories
 
-\`architecture\` · \`decisions\` · \`requirements\` · \`concepts\` · \`roadmap\` · \`landscape\` · \`open-questions\``;
+\`architecture\` · \`decisions\` · \`requirements\` · \`concepts\` · \`roadmap\` · \`landscape\` · \`open-questions\`
+
+### Keeping these instructions current
+
+This block is generated by Gnosys and can drift from the installed version. After upgrading Gnosys (or if guidance here looks stale), run \`gnosys sync\` to regenerate this section in every detected IDE rules file (CLAUDE.md, .cursor/rules, .codex). Your user preferences and project conventions are re-injected at the same time.`;
 }
 // ─── Content generation ─────────────────────────────────────────────────
 /**

package/dist/lib/setup.js

@@ -14,6 +14,7 @@ import fsSync from "fs";
 import path from "path";
 import os from "os";
 import { execSync } from "child_process";
+import { guardInteractiveStdin } from "./interactiveGuard.js";
 import { loadConfig, updateConfig, resolveTaskModel, getProviderModel, } from "./config.js";
 import { isApiKeyValidationError, validateModel } from "./modelValidation.js";
 import { buildOpenRouterTiers, OPENROUTER_STATIC_TIERS, } from "./openrouterTiers.js";
@@ -1162,6 +1163,7 @@ export async function runSetup(opts) {
         };
     }
     // ─── Interactive mode ─────────────────────────────────────────────────
+    guardInteractiveStdin("setup");
     const rl = createInterface({ input: stdin, output: stdout });
     let setupCompleted = false;
     // Handle Ctrl+C gracefully — only show "cancelled" if setup didn't finish
@@ -2130,6 +2132,8 @@ export function buildTaskModelsPatchFromAccepted(accepted, currentByTask, select
 export async function runModelsSetup(opts = {}) {
     const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
     const ownsRl = !opts.rl;
+    if (ownsRl)
+        guardInteractiveStdin("setup models");
     const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
     try {
         const { Header } = await import("./setup/ui/header.js");
@@ -2519,6 +2523,8 @@ async function runModelsTaskRoutingSetup(ctx) {
 export async function runDreamSetup(opts = {}) {
     const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
     const ownsRl = !opts.rl;
+    if (ownsRl)
+        guardInteractiveStdin("setup dream");
     const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
     try {
         // v5.9.3 Screen 7 — three grouped sub-screens (7.0 enable, 7.1
@@ -2757,8 +2763,11 @@ export async function runDreamSetup(opts = {}) {
         // Reset consecutive failure counter on a fresh setup so Layer 4
         // doesn't fire immediately based on stale history.
         localDb.resetDreamConsecutiveFailures();
-        const { installDreamLaunchAgent } = await import("./dreamLaunchd.js");
+        const { installDreamLaunchAgent, loadDreamLaunchAgent } = await import("./dreamLaunchd.js");
         const launchdPath = installDreamLaunchAgent();
+        // Best-effort immediate activation so the schedule doesn't wait for the
+        // next login (v5.14.x sprint, pre-approved).
+        const launchdLoad = launchdPath ? loadDreamLaunchAgent(launchdPath) : null;
         localDb.close();
         remoteDb?.close();
         // Final Diff block per the design — provider/machine + the two
@@ -2789,6 +2798,8 @@ export async function runDreamSetup(opts = {}) {
         printStatus("progress", `scheduled dream checks run nightly (${scheduleStartHour}:00-${scheduleEndHour}:00) on ${dreamerName}`);
         if (launchdPath)
             printStatus("ok", "launchd agent installed", launchdPath);
+        if (launchdLoad)
+            printStatus(launchdLoad.ok ? "ok" : "warn", launchdLoad.message);
         printStatus("progress", "check status anytime with `gnosys status --system`");
     }
     finally {

package/dist/lib/setupKeys.js

@@ -1,5 +1,6 @@
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
+import { guardInteractiveStdin } from "./interactiveGuard.js";
 import fs from "fs/promises";
 import fsSync from "fs";
 import os from "os";
@@ -522,6 +523,8 @@ export function renderProviderTable(providers) {
 }
 export async function runKeysSetup(opts) {
     const ownReadline = !opts?.rl;
+    if (ownReadline)
+        guardInteractiveStdin("setup keys");
     const rl = opts?.rl ?? createInterface({ input: stdin, output: stdout });
     try {
         while (true) {

package/dist/lib/statusCommand.js

@@ -86,6 +86,22 @@ export async function runStatusCommand(opts, deps) {
             }
             const data = await collectDashboardData(resolver, cfg, deps.pkgVersion, dashDb ?? undefined);
             console.log(opts.json ? formatDashboardJSON(data) : formatDashboard(data));
+            // v5.15: dream launchd agent health (read-only — repair happens in
+            // `gnosys upgrade`). macOS + dream enabled only; skip in JSON mode
+            // to keep the JSON payload shape stable.
+            if (!opts.json && process.platform === "darwin" && cfg.dream?.enabled) {
+                const { checkDreamLaunchAgent } = await import("./dreamLaunchd.js");
+                const health = checkDreamLaunchAgent();
+                console.log("\nDream launchd agent:");
+                if (health.healthy) {
+                    console.log("  ✓ healthy (installed, loaded, node + cli paths valid)");
+                }
+                else {
+                    for (const problem of health.problems) {
+                        console.log(`  ⚠ ${problem}`);
+                    }
+                }
+            }
         }
         catch (err) {
             console.error(`Error: ${err instanceof Error ? err.message : err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.14.0",
+  "version": "5.15.2",
   "description": "Gnosys — Persistent Memory for AI Agents. Sandbox-first runtime, central SQLite brain, federated search, Dream Mode, Web Knowledge Base, Obsidian export.",
   "type": "module",
   "main": "dist/index.js",