gnosys 5.13.1 → 5.15.1

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;
@@ -1307,6 +1313,15 @@ program
     const { runRecallCommand } = await import("./lib/recallCommand.js");
     await runRecallCommand(query, opts);
 });
+// ─── gnosys recall-hook ──────────────────────────────────────────────────
+program
+    .command("recall-hook")
+    .description("Claude Code hook entry — reads the hook event JSON from stdin and prints a <gnosys-recall> context block. Wired automatically by gnosys init into UserPromptSubmit + SessionStart.")
+    .option("--limit <n>", "Max memories to inject (default from config)")
+    .action(async (opts) => {
+    const { runRecallHookCommand } = await import("./lib/recallHookCommand.js");
+    await runRecallHookCommand(opts);
+});
 // ─── gnosys audit ────────────────────────────────────────────────────────
 program
     .command("audit")
@@ -1855,10 +1870,13 @@ if (!isTestEnv()) {
             // console.log during boot corrupts the protocol and the host (Grok, Codex,
             // etc.) sees the server as [unavailable]. Suppress the nag in serve mode.
             const isServeCmd = process.argv.slice(2).some(a => a === "serve");
+            // v5.14.0: recall-hook runs on every Claude Code prompt — keep its
+            // stderr quiet too so hook error logs stay clean.
+            const isHookCmd = process.argv.slice(2).some(a => a === "recall-hook");
             // v5.9.3 Phase H: fire on any mismatch (upgrade OR downgrade).
             const mismatch = lastVersion !== null && lastVersion !== undefined &&
                 compareSemver(currentVersion, lastVersion) !== 0;
-            if (mismatch && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd) {
+            if (mismatch && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd && !isHookCmd) {
                 // v5.9.3 Phase H: emit on STDERR (was stdout). Safer invariant per
                 // deci-045 — stdout is reserved for command output.
                 const isMajorOrMinor = (() => {

package/dist/index.js

@@ -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
@@ -2246,7 +2247,7 @@ async function reindexAllStores() {
 //
 // Priority 1 + audience: assistant = hosts inject this before every message.
 regResource("gnosys_recall", "gnosys://recall", {
-    description: "Automatic memory injection. Hosts read this resource on every turn to inject the most relevant memories as context. Returns a <gnosys-recall> block with [[wikilinks]] and relevance scores. Priority 1 (highest) — designed for always-on context injection without any tool call. Configure aggressiveness in gnosys.json: recall.aggressive (default: true).",
+    description: "Top-memory injection block for hosts that read MCP resources. Returns a <gnosys-recall> block with [[wikilinks]] and relevance scores. NOTE: most hosts (Claude Code, Cursor) do NOT auto-read MCP resources per turn — for true automatic injection use the hooks `gnosys init` installs (UserPromptSubmit/SessionStart → `gnosys recall-hook`). Configure aggressiveness in gnosys.json: recall.aggressive (default: true).",
     mimeType: "text/markdown",
     annotations: {
         audience: ["assistant"],
@@ -2294,7 +2295,7 @@ regResource("gnosys_recall", "gnosys://recall", {
 // ─── Tool: gnosys_recall (query-specific fallback) ──────────────────────
 // For hosts that don't support MCP Resources, or when the agent wants to
 // recall memories for a specific query. The resource above is preferred.
-regTool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. Prefer the gnosys://recall MCP Resource for automatic injection (no tool call needed).", {
+regTool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. A wildcard query ('*') returns the top memories by reinforcement/confidence/recency. Hosts with gnosys hooks installed (via gnosys init) already get this automatically per prompt.", {
     query: z
         .string()
         .describe("What the agent is currently working on. Use keywords. Example: 'auth JWT middleware' or 'database migration schema'"),

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/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/projectIdentity.js

@@ -202,29 +202,61 @@ export async function configureClaudeCode(projectDir) {
     catch {
         // No settings yet
     }
-    // Build the Gnosys SessionStart hook
+    // v5.14.0: the hook command is `gnosys recall-hook` — it reads the hook
+    // event JSON from stdin (per the Claude Code hooks contract) and prints
+    // a <gnosys-recall> block, which Claude Code adds to the model context.
+    // Pre-5.14 installs wrote `gnosys recall --query ... --projectRoot ...`,
+    // options that never existed — the hook failed silently on every
+    // session start. Detect and heal that shape below.
+    const hookCommand = "gnosys recall-hook 2>/dev/null || true";
     const gnosysHook = {
         type: "command",
-        command: "gnosys recall --query \"session start\" --projectRoot \"$CLAUDE_PROJECT_DIR\" 2>/dev/null || true",
+        command: hookCommand,
         timeout: 10,
     };
-    // Merge into existing hooks without clobbering other SessionStart hooks
+    const isGnosysHookCmd = (h) => typeof h.command === "string" &&
+        (h.command.includes("gnosys recall-hook") ||
+            // the exact broken pre-5.14 shape only — a user's own `gnosys recall
+            // <topic>` hook must not count as "already configured"
+            h.command.includes("gnosys recall --query"));
+    const isBrokenLegacyCmd = (h) => typeof h.command === "string" && h.command.includes("gnosys recall --query");
+    // Merge into existing hooks without clobbering other entries
     const hooks = (settings.hooks || {});
+    let changed = false;
+    // Heal the broken legacy command wherever it appears
+    for (const eventName of Object.keys(hooks)) {
+        for (const entry of (hooks[eventName] || [])) {
+            const entryHooks = (entry.hooks || []);
+            for (const h of entryHooks) {
+                if (isBrokenLegacyCmd(h)) {
+                    h.command = hookCommand;
+                    changed = true;
+                }
+            }
+        }
+    }
+    // SessionStart: top memories at startup/resume/compact
     const sessionStartEntries = (hooks.SessionStart || []);
-    // Check if a Gnosys hook already exists
-    const hasGnosysHook = sessionStartEntries.some((entry) => {
-        const entryHooks = (entry.hooks || []);
-        return entryHooks.some((h) => typeof h.command === "string" && h.command.includes("gnosys recall"));
-    });
-    if (!hasGnosysHook) {
-        sessionStartEntries.push({
-            matcher: "startup|resume|compact",
-            hooks: [gnosysHook],
-        });
+    const hasSessionHook = sessionStartEntries.some((entry) => (entry.hooks || []).some(isGnosysHookCmd));
+    if (!hasSessionHook) {
+        sessionStartEntries.push({ matcher: "startup|resume|compact", hooks: [gnosysHook] });
         hooks.SessionStart = sessionStartEntries;
+        changed = true;
+    }
+    // UserPromptSubmit: per-prompt recall with the prompt text as the query —
+    // this is the "automatic memory injection" path (no matcher: always fires)
+    const promptEntries = (hooks.UserPromptSubmit || []);
+    const hasPromptHook = promptEntries.some((entry) => (entry.hooks || []).some(isGnosysHookCmd));
+    if (!hasPromptHook) {
+        promptEntries.push({ hooks: [gnosysHook] });
+        hooks.UserPromptSubmit = promptEntries;
+        changed = true;
+    }
+    if (changed) {
         settings.hooks = hooks;
         await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
     }
+    const hasGnosysHook = !changed;
     // v5.8.4: also register the MCP server itself (not just the recall hook),
     // so `gnosys init` is a one-stop shop. Previously the user had to ALSO
     // run `gnosys setup` for agents to actually call gnosys MCP tools.
@@ -234,7 +266,9 @@ export async function configureClaudeCode(projectDir) {
         configured: true,
         filePath: settingsPath,
         details: [
-            hasGnosysHook ? "SessionStart hook already configured" : "Added SessionStart hook",
+            hasGnosysHook
+                ? "Recall hooks already configured"
+                : "Recall hooks configured (SessionStart + UserPromptSubmit → gnosys recall-hook)",
             mcpResult.success ? mcpResult.message : `MCP register skipped: ${mcpResult.message}`,
         ].join("; "),
     };

package/dist/lib/recall.d.ts

@@ -62,9 +62,10 @@ interface RecallMemory {
  */
 export declare function recall(query: string, options: {
     limit?: number;
-    search: GnosysSearch;
-    resolver: GnosysResolver;
-    storePath: string;
+    /** Optional in v5.14: callers on the DB fast path (hooks) skip the file-store deps. */
+    search?: GnosysSearch;
+    resolver?: GnosysResolver;
+    storePath?: string;
     traceId?: string;
     recallConfig?: RecallConfig;
     /** v2.0: When provided, recall uses SQLite directly — no filesystem reads */

package/dist/lib/recall.js

@@ -72,6 +72,17 @@ export async function recall(query, options) {
         return recallFromDb(query, options.gnosysDb, limit, cfg, options.traceId, options.pendingOverlay);
     }
     // ─── v1.x legacy path (filesystem + search.db) ────────────────────
+    // v5.14: DB-only callers (recall-hook) pass no file-store deps; without
+    // them and without a central DB there is nothing to search.
+    if (!options.search || !options.resolver) {
+        return {
+            memories: [],
+            totalActive: 0,
+            totalArchived: 0,
+            recallTimeMs: Math.round((performance.now() - start) * 100) / 100,
+            aggressive: cfg.aggressive,
+        };
+    }
     const memories = [];
     // Step 1: Fast keyword search on active memories (FTS5 — sub-10ms)
     const fetchLimit = Math.max(limit * 2, 15);
@@ -96,7 +107,7 @@ export async function recall(query, options) {
     }
     // Step 2: Archive fallback if active results are thin
     let totalArchived = 0;
-    if (memories.length < limit) {
+    if (memories.length < limit && options.storePath) {
         try {
             const archive = new GnosysArchive(options.storePath);
             if (archive.isAvailable()) {

package/dist/lib/recallCommand.js

@@ -70,7 +70,7 @@ export async function runRecallCommand(query, opts) {
         }
         return;
     }
-    // Legacy file-based recall
+    // Default recall path
     const resolver = new GnosysResolver();
     await resolver.resolve();
     const stores = resolver.getStores();
@@ -91,14 +91,29 @@ export async function runRecallCommand(query, opts) {
     // Build search index
     const search = new GnosysSearch(storePath);
     await search.addStoreMemories(stores[0].store);
-    const result = await recall(query, {
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-        search,
-        resolver,
-        storePath,
-        traceId: opts.traceId,
-        recallConfig,
-    });
+    // v5.14.0: recall from the central DB (the brain) like the MCP tool
+    // does — the CLI previously only searched the project file store, so
+    // `gnosys recall` (and the SessionStart hook built on it) returned
+    // nothing on DB-only installs. Snapshot-aware via clientReadResolve;
+    // falls back to the file-store path when no central DB exists.
+    const { resolveClientRead } = await import("./clientReadResolve.js");
+    const clientRead = resolveClientRead();
+    let result;
+    try {
+        result = await recall(query, {
+            limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+            search,
+            resolver,
+            storePath,
+            traceId: opts.traceId,
+            recallConfig,
+            gnosysDb: clientRead?.db,
+            pendingOverlay: clientRead?.pendingOverlay,
+        });
+    }
+    finally {
+        clientRead?.release();
+    }
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
     }

package/dist/lib/recallHookCommand.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `gnosys recall-hook` — Claude Code hook entry point (v5.14.0).
+ *
+ * This is what makes "automatic memory injection" real: Claude Code never
+ * auto-reads MCP resources, but its hooks contract
+ * (code.claude.com/docs/en/hooks.md) adds a hook's plain stdout to the
+ * model context on exit 0. `gnosys init` wires this command into
+ * UserPromptSubmit (every prompt, query = the prompt text) and
+ * SessionStart (startup/resume/compact, wildcard = top memories).
+ *
+ * Contract obligations:
+ *  - FAST: runs on every prompt. DB fast path only — no file stores, no
+ *    embeddings, no model loads. (~150ms cold including node startup.)
+ *  - NEVER breaks the prompt: always exit 0; every failure is silent.
+ *  - Empty stdout when there is nothing to inject (no noise strings).
+ *  - Output stays well under the 10,000-char hook cap.
+ */
+export type HookEvent = {
+    hook_event_name?: string;
+    prompt_text?: string;
+    /** Older docs name the field `prompt`; accept both. */
+    prompt?: string;
+    source?: string;
+    cwd?: string;
+};
+/** Parse the hook event JSON into a recall query ("*" = top memories). */
+export declare function hookQueryFromStdin(raw: string): string;
+export declare function runRecallHookCommand(opts?: {
+    limit?: string;
+}): Promise<void>;

package/dist/lib/recallHookCommand.js

@@ -0,0 +1,85 @@
+/**
+ * `gnosys recall-hook` — Claude Code hook entry point (v5.14.0).
+ *
+ * This is what makes "automatic memory injection" real: Claude Code never
+ * auto-reads MCP resources, but its hooks contract
+ * (code.claude.com/docs/en/hooks.md) adds a hook's plain stdout to the
+ * model context on exit 0. `gnosys init` wires this command into
+ * UserPromptSubmit (every prompt, query = the prompt text) and
+ * SessionStart (startup/resume/compact, wildcard = top memories).
+ *
+ * Contract obligations:
+ *  - FAST: runs on every prompt. DB fast path only — no file stores, no
+ *    embeddings, no model loads. (~150ms cold including node startup.)
+ *  - NEVER breaks the prompt: always exit 0; every failure is silent.
+ *  - Empty stdout when there is nothing to inject (no noise strings).
+ *  - Output stays well under the 10,000-char hook cap.
+ */
+/** Max chars of the user prompt used as the recall query. */
+const MAX_QUERY_CHARS = 400;
+/** Keep comfortably under Claude Code's 10k hook-output cap. */
+const MAX_OUTPUT_CHARS = 8_000;
+/** Parse the hook event JSON into a recall query ("*" = top memories). */
+export function hookQueryFromStdin(raw) {
+    try {
+        const evt = JSON.parse(raw);
+        const prompt = evt.prompt_text ?? evt.prompt;
+        if (typeof prompt === "string" && prompt.trim().length > 0) {
+            return prompt.trim().slice(0, MAX_QUERY_CHARS);
+        }
+    }
+    catch {
+        // Not JSON (manual invocation / future contract change) — wildcard.
+    }
+    return "*";
+}
+async function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return "";
+    return new Promise((resolve) => {
+        let data = "";
+        const timer = setTimeout(() => resolve(data), timeoutMs);
+        timer.unref?.();
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => {
+            clearTimeout(timer);
+            resolve(data);
+        });
+        process.stdin.on("error", () => {
+            clearTimeout(timer);
+            resolve(data);
+        });
+    });
+}
+export async function runRecallHookCommand(opts = {}) {
+    try {
+        const raw = await readStdin(1_000);
+        const query = hookQueryFromStdin(raw);
+        const { resolveClientRead } = await import("./clientReadResolve.js");
+        const clientRead = resolveClientRead();
+        if (!clientRead)
+            return; // no central DB — inject nothing, exit 0
+        try {
+            const { recall, formatRecall } = await import("./recall.js");
+            const result = await recall(query, {
+                limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+                gnosysDb: clientRead.db,
+                pendingOverlay: clientRead.pendingOverlay,
+                traceId: "claude-code-hook",
+            });
+            if (result.memories.length === 0)
+                return; // empty stdout = no injection
+            const block = formatRecall(result);
+            process.stdout.write(block.length > MAX_OUTPUT_CHARS ? `${block.slice(0, MAX_OUTPUT_CHARS)}\n</gnosys-recall>\n` : `${block}\n`);
+        }
+        finally {
+            clientRead.release();
+        }
+    }
+    catch {
+        // Never fail the user's prompt over memory recall.
+    }
+}

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.13.1",
+  "version": "5.15.1",
   "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",