monomind 2.1.0 → 2.1.4

package/packages/@monomind/cli/dist/src/commands/org.js

@@ -19,12 +19,20 @@ function validateOrgName(name) {
     }
     return { ok: true, name };
 }
-/** Config filenames for real orgs under orgsDir — excludes org-internal
- * artifact files (state/goals/threads/etc) that share the .json extension. */
-const ORG_ARTIFACT_SUFFIXES = ['-state', '-goals', '-threads', '-activity', '-approvals', '-members', '-secrets', '-budgets'];
+/** Suffixes of org-internal artifact files (state/goals/threads/etc) that
+ * share the `<org>.json`/`.jsonl` naming pattern with the org's own config
+ * file. Single source of truth for both listOrgConfigFiles() (which must
+ * exclude them when discovering real org configs) and deleteAction (which
+ * must remove all of them when deleting an org). */
+const ORG_ARTIFACT_SUFFIXES = [
+    '-state', '-goals', '-threads', '-activity', '-approvals', '-members', '-secrets', '-budgets',
+    '-routines', '-issues', '-projects', '-workspaces', '-worktrees', '-environments',
+    '-plugins', '-adapters', '-join-requests', '-bootstrap', '-project-workspaces',
+    '-approval-comments', '-skills',
+];
 function listOrgConfigFiles(orgsDir) {
     return readdirSync(orgsDir)
-        .filter(f => f.endsWith('.json') && !ORG_ARTIFACT_SUFFIXES.some(suf => f.includes(suf)));
+        .filter(f => f.endsWith('.json') && !f.startsWith('._') && !ORG_ARTIFACT_SUFFIXES.some(suf => f.includes(suf)));
 }
 /** Remove a lingering stopfile so a fresh `org run` doesn't self-terminate. */
 export const clearStopfile = (cwd, name) => {
@@ -32,22 +40,27 @@ export const clearStopfile = (cwd, name) => {
 };
 const runAction = async (ctx) => {
     if (!ctx.args[0])
-        return { success: false, message: 'org name required: monomind org run <name> [--task "..."] [--serve] [--port N]' };
+        return { success: false, message: 'org name required: monomind org run <name> [--task "..."]' };
     const validated = validateOrgName(ctx.args[0]);
     if (!validated.ok)
         return validated.result;
     const name = validated.name;
+    // A repeated --task flag is promoted to an array by the parser (deliberate,
+    // documented behavior elsewhere — repeats never silently drop a value); a
+    // plain `as string` cast would let that array flow straight into the org's
+    // goal and get stringified as "a,b" with no warning. Checked before any
+    // side effects (starting the xdeliver listener) run.
+    const taskFlag = ctx.flags['task'];
+    if (Array.isArray(taskFlag))
+        return { success: false, message: '--task was passed more than once — pass it exactly once' };
     const crossProcess = ctx.flags['crossProcess'] !== false;
     const daemon = new OrgDaemon(ctx.cwd, { crossProcess });
     let srv;
-    if (ctx.flags['serve'] !== false) {
-        const port = Number(ctx.flags['port'] ?? 4243);
-        srv = await startOrgServer(daemon, port);
-        log(output.info(`org live view: http://localhost:${srv.port}`));
-        if (crossProcess)
-            daemon.setInboxUrl(`http://127.0.0.1:${srv.port}`);
+    if (crossProcess) {
+        srv = await startOrgServer(daemon, 0);
+        daemon.setInboxUrl(`http://127.0.0.1:${srv.port}`);
     }
-    const running = await daemon.startOrg(name, ctx.flags['task']);
+    const running = await daemon.startOrg(name, taskFlag);
     log(output.info(`org ${name} running (${running.def.roles.length} agents, run ${running.run}) — Ctrl-C or "monomind org stop ${name}" to stop`));
     // stopfile poll lets `org stop` work from another terminal;
     // clear any stale stopfile from a previous run before polling
@@ -101,10 +114,12 @@ const statusAction = async (ctx) => {
 const serveAction = async (ctx) => {
     const crossProcess = ctx.flags['crossProcess'] !== false;
     const daemon = new OrgDaemon(ctx.cwd, { crossProcess });
-    const srv = await startOrgServer(daemon, Number(ctx.flags['port'] ?? 4243));
-    log(output.info(`org daemon serving on http://localhost:${srv.port} — Ctrl-C to stop`));
-    if (crossProcess)
+    let srv;
+    if (crossProcess) {
+        srv = await startOrgServer(daemon, 0);
         daemon.setInboxUrl(`http://127.0.0.1:${srv.port}`);
+    }
+    log(output.info('org daemon serving — Ctrl-C to stop'));
     // schedule orgs whose definition declares an interval (e.g. "15m", "2h")
     const { OrgScheduler, parseSchedule } = await import('../orgrt/scheduler.js');
     const sched = new OrgScheduler(async (name, intervalMs) => {
@@ -137,7 +152,7 @@ const serveAction = async (ctx) => {
     });
     const orgDir = join(ctx.cwd, ORG_DIR);
     if (existsSync(orgDir)) {
-        for (const f of readdirSync(orgDir).filter(f => f.endsWith('.json'))) {
+        for (const f of listOrgConfigFiles(orgDir)) {
             try {
                 const def = JSON.parse(readFileSync(join(orgDir, f), 'utf8'));
                 const ms = parseSchedule(def.schedule);
@@ -150,13 +165,15 @@ const serveAction = async (ctx) => {
                     log(output.info(`scheduled org ${stem} every ${Math.round(ms / 60_000)}m`));
                 }
             }
-            catch { /* skip unparseable org file */ }
+            catch (err) {
+                log(output.warning(`org file ${f}: could not parse — skipping (${err instanceof Error ? err.message : 'invalid JSON'})`));
+            }
         }
     }
     await new Promise(r => { process.once('SIGINT', () => r()); process.once('SIGTERM', () => r()); });
     sched.stop();
     await daemon.stopAll();
-    srv.close();
+    srv?.close();
     return { success: true };
 };
 const testLoopAction = async (ctx) => {
@@ -191,7 +208,7 @@ const deleteAction = async (ctx) => {
         log(output.error('Usage: monomind org delete <name>'));
         return { success: false, message: 'org name required' };
     }
-    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(orgName)) {
+    if (!ORG_NAME_RE.test(orgName)) {
         log(output.error(`Invalid org name: ${orgName}`));
         return { success: false, message: 'invalid org name' };
     }
@@ -208,12 +225,8 @@ const deleteAction = async (ctx) => {
         log(output.error(`Org not found: ${orgName}`));
         return { success: false, message: 'org not found' };
     }
-    const suffixes = ['', '-state', '-goals', '-routines', '-approvals', '-activity',
-        '-issues', '-members', '-projects', '-workspaces', '-worktrees', '-environments',
-        '-plugins', '-adapters', '-budgets', '-threads', '-secrets', '-join-requests',
-        '-bootstrap', '-project-workspaces', '-approval-comments', '-skills'];
     let removed = 0;
-    for (const suf of suffixes) {
+    for (const suf of ['', ...ORG_ARTIFACT_SUFFIXES]) {
         for (const ext of ['.json', '.jsonl']) {
             const f = join(orgsDir, `${orgName}${suf}${ext}`);
             try {
@@ -248,7 +261,7 @@ const deleteAction = async (ctx) => {
 };
 const markCompleteAction = async (ctx) => {
     const orgName = ctx.args[0];
-    if (!orgName || !/^[a-z0-9][a-z0-9_-]*$/i.test(orgName)) {
+    if (!orgName || !ORG_NAME_RE.test(orgName)) {
         log(output.error('Usage: monomind org mark-complete <name>'));
         return { success: false, message: 'valid org name required' };
     }
@@ -284,8 +297,6 @@ export const orgCommand = {
             name: 'run', description: 'Start an org (foreground daemon)',
             options: [
                 { name: 'task', description: 'Override the org goal for this run', type: 'string' },
-                { name: 'serve', description: 'Serve the live dashboard (default true)', type: 'boolean', default: true },
-                { name: 'port', description: 'Live dashboard port', type: 'number', default: 4243 },
                 { name: 'cross-process', description: 'Discover and message orgs hosted by other monomind processes on this machine (default true)', type: 'boolean', default: true },
             ],
             examples: [{ command: 'monomind org run growth --task "weekly report"', description: 'Run the growth org once with a task' }],
@@ -296,7 +307,6 @@ export const orgCommand = {
         {
             name: 'serve', description: 'Start the daemon server only (hosts scheduled orgs)',
             options: [
-                { name: 'port', description: 'Port', type: 'number', default: 4243 },
                 { name: 'cross-process', description: 'Discover and message orgs hosted by other monomind processes on this machine (default true)', type: 'boolean', default: true },
             ],
             action: serveAction,
@@ -315,7 +325,14 @@ export const orgCommand = {
         { name: 'mark-complete', description: 'Manually close a stale/crashed run', action: markCompleteAction },
     ],
     examples: [{ command: 'monomind org run my-org', description: 'Run an org under full daemon control' }],
-    action: async () => ({ success: false, message: 'usage: monomind org <run|stop|status|serve|test-loop|list|delete|mark-complete>' }),
+    action: async () => {
+        // index.ts's dispatcher never prints result.message on a failed action —
+        // it only exits with result.exitCode — so this must log itself or bare
+        // `monomind org` exits silently with code 1 and zero output.
+        const message = 'usage: monomind org <run|stop|status|serve|test-loop|list|delete|mark-complete>';
+        log(output.error(message));
+        return { success: false, message };
+    },
 };
 export default orgCommand;
 //# sourceMappingURL=org.js.map

package/packages/@monomind/cli/dist/src/commands/platforms.d.ts

@@ -5,7 +5,7 @@
  * github.com/monoes/monomind
  */
 import type { Command } from '../types.js';
-export declare const SUPPORTED_PLATFORMS: readonly ["claude", "gemini", "cursor", "vscode", "copilot", "opencode", "aider", "kiro", "trae", "claw", "droid", "antigravity", "hermes", "codex"];
+export declare const SUPPORTED_PLATFORMS: readonly ['claude', 'gemini', 'cursor', 'vscode', 'copilot', 'opencode', 'aider', 'kiro', 'trae', 'claw', 'droid', 'antigravity', 'hermes', 'codex'];
 export type Platform = typeof SUPPORTED_PLATFORMS[number];
 export declare const platformsCommand: Command;
 //# sourceMappingURL=platforms.d.ts.map

package/packages/@monomind/cli/dist/src/init/executor.js

@@ -575,6 +575,13 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
             const destHelpersDir = path.join(targetDir, '.claude', 'helpers');
             // Copy top-level critical files atomically
             const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs', 'graphify-freshen.cjs'];
+            // Generated fallback for any critical helper missing from the source dir itself
+            // (e.g. the published npm template lacking auto-memory-hook.mjs).
+            const criticalGenerators = {
+                'hook-handler.cjs': generateHookHandler,
+                'intelligence.cjs': generateIntelligenceStub,
+                'auto-memory-hook.mjs': generateAutoMemoryHook,
+            };
             for (const helperName of criticalHelpers) {
                 const targetPath = path.join(destHelpersDir, helperName);
                 const sourcePath = path.join(sourceHelpersForUpgrade, helperName);
@@ -594,6 +601,17 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                     catch { }
                     fs.renameSync(tmp, targetPath);
                 }
+                else if (!fs.existsSync(targetPath) && criticalGenerators[helperName]) {
+                    const content = criticalGenerators[helperName]();
+                    const tmp = `${targetPath}.${process.pid}.tmp`;
+                    fs.writeFileSync(tmp, content, 'utf-8');
+                    try {
+                        fs.chmodSync(tmp, 0o755);
+                    }
+                    catch { }
+                    fs.renameSync(tmp, targetPath);
+                    result.created.push(`.claude/helpers/${helperName}`);
+                }
             }
             // Always recursively sync subdirectories (utils/, handlers/) — required by hook-handler.cjs.
             // Uses recursive copy so any future nested subdirs are also covered.
@@ -1222,7 +1240,6 @@ async function writeHelpers(targetDir, options, result) {
     const sourceHelpersDir = findSourceHelpersDir(options.sourceBaseDir);
     // Try to copy existing helpers from source first (recursive — includes utils/ and handlers/)
     if (sourceHelpersDir && fs.existsSync(sourceHelpersDir)) {
-        let copiedCount = 0;
         const copyRecursive = (srcDir, destDir, relBase) => {
             fs.mkdirSync(destDir, { recursive: true });
             for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
@@ -1242,7 +1259,6 @@ async function writeHelpers(targetDir, options, result) {
                             fs.chmodSync(destPath, '755');
                         }
                         result.created.files.push(`.claude/helpers/${relPath}`);
-                        copiedCount++;
                     }
                     else {
                         result.skipped.push(`.claude/helpers/${relPath}`);
@@ -1251,11 +1267,12 @@ async function writeHelpers(targetDir, options, result) {
             }
         };
         copyRecursive(sourceHelpersDir, helpersDir, '');
-        if (copiedCount > 0) {
-            return; // Skip generating if we copied from source
-        }
     }
-    // Fall back to generating helpers if source not available
+    // Always run the fallback generator too — it only fills in files still missing
+    // after the source copy above (it no-ops on anything the copy already wrote).
+    // Without this, a source dir that's present but incomplete (e.g. missing
+    // auto-memory-hook.mjs) silently ships a project wired to hooks that reference
+    // a file that was never installed.
     const helpers = {
         'pre-commit': generatePreCommitHook(),
         'post-commit': generatePostCommitHook(),
@@ -1268,6 +1285,13 @@ async function writeHelpers(targetDir, options, result) {
     };
     for (const [name, content] of Object.entries(helpers)) {
         const filePath = path.join(helpersDir, name);
+        // If the source dir has this file, copyRecursive above already applied
+        // the correct (force-aware) copy — never let this generated fallback
+        // clobber it with a bare-bones stub. Only step in when source truly
+        // doesn't have the file, regardless of `force`.
+        const inSource = !!(sourceHelpersDir && fs.existsSync(path.join(sourceHelpersDir, name)));
+        if (inSource)
+            continue;
         if (!fs.existsSync(filePath) || options.force) {
             atomicWriteFile(filePath, content);
             // Make shell scripts executable

package/packages/@monomind/cli/dist/src/mcp-tools/auto-install.d.ts

@@ -47,12 +47,12 @@ export declare function resetInstallAttempts(): void;
  */
 export declare const OPTIONAL_PACKAGES: {
     readonly 'monofence-ai': {
-        readonly description: "AI manipulation defense (prompt injection, PII detection)";
-        readonly tools: readonly ["aidefence_scan", "aidefence_analyze", "aidefence_stats", "aidefence_learn"];
+        readonly description: 'AI manipulation defense (prompt injection, PII detection)';
+        readonly tools: readonly ['aidefence_scan', 'aidefence_analyze', 'aidefence_stats', 'aidefence_learn'];
     };
     readonly 'onnxruntime-node': {
-        readonly description: "ONNX runtime for neural network inference";
-        readonly tools: readonly ["neural_*"];
+        readonly description: 'ONNX runtime for neural network inference';
+        readonly tools: readonly ['neural_*'];
     };
 };
 declare const _default: {
@@ -62,12 +62,12 @@ declare const _default: {
     resetInstallAttempts: typeof resetInstallAttempts;
     OPTIONAL_PACKAGES: {
         readonly 'monofence-ai': {
-            readonly description: "AI manipulation defense (prompt injection, PII detection)";
-            readonly tools: readonly ["aidefence_scan", "aidefence_analyze", "aidefence_stats", "aidefence_learn"];
+            readonly description: 'AI manipulation defense (prompt injection, PII detection)';
+            readonly tools: readonly ['aidefence_scan', 'aidefence_analyze', 'aidefence_stats', 'aidefence_learn'];
         };
         readonly 'onnxruntime-node': {
-            readonly description: "ONNX runtime for neural network inference";
-            readonly tools: readonly ["neural_*"];
+            readonly description: 'ONNX runtime for neural network inference';
+            readonly tools: readonly ['neural_*'];
         };
     };
 };

package/packages/@monomind/cli/dist/src/mcp-tools/coherence/types.d.ts

@@ -69,8 +69,8 @@ export declare const CoherenceInputSchema: z.ZodObject<{
     vectors: z.ZodArray<z.ZodArray<z.ZodNumber, "many">, "many">;
     threshold: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    threshold: number;
     vectors: number[][];
+    threshold: number;
 }, {
     vectors: number[][];
     threshold?: number | undefined;
@@ -98,10 +98,10 @@ export declare const SpectralInputSchema: z.ZodObject<{
     analyzeType: z.ZodDefault<z.ZodEnum<["stability", "clustering", "connectivity"]>>;
 }, "strip", z.ZodTypeAny, {
     matrix: number[][];
-    analyzeType: "stability" | "clustering" | "connectivity";
+    analyzeType: "clustering" | "connectivity" | "stability";
 }, {
     matrix: number[][];
-    analyzeType?: "stability" | "clustering" | "connectivity" | undefined;
+    analyzeType?: "clustering" | "connectivity" | "stability" | undefined;
 }>;
 export type SpectralInput = z.infer<typeof SpectralInputSchema>;
 export interface SpectralResult {
@@ -150,15 +150,15 @@ export declare const CausalInputSchema: z.ZodObject<{
         nodes: string[];
         edges: [string, string][];
     };
-    outcome: string;
     intervention: string;
+    outcome: string;
 }, {
     graph: {
         nodes: string[];
         edges: [string, string][];
     };
-    outcome: string;
     intervention: string;
+    outcome: string;
 }>;
 export type CausalInput = z.infer<typeof CausalInputSchema>;
 export interface CausalResult {
@@ -185,13 +185,13 @@ export declare const AgentStateSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     agentId: string;
     embedding: number[];
-    metadata?: Record<string, unknown> | undefined;
     vote?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
 }, {
     agentId: string;
     embedding: number[];
-    metadata?: Record<string, unknown> | undefined;
     vote?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
 }>;
 export type AgentState = z.infer<typeof AgentStateSchema>;
 export declare const ConsensusInputSchema: z.ZodObject<{
@@ -203,29 +203,29 @@ export declare const ConsensusInputSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         agentId: string;
         embedding: number[];
-        metadata?: Record<string, unknown> | undefined;
         vote?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }, {
         agentId: string;
         embedding: number[];
-        metadata?: Record<string, unknown> | undefined;
         vote?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }>, "many">;
     threshold: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    threshold: number;
     agentStates: {
         agentId: string;
         embedding: number[];
-        metadata?: Record<string, unknown> | undefined;
         vote?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }[];
+    threshold: number;
 }, {
     agentStates: {
         agentId: string;
         embedding: number[];
-        metadata?: Record<string, unknown> | undefined;
         vote?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
     }[];
     threshold?: number | undefined;
 }>;
@@ -247,11 +247,11 @@ export declare const SimplexSchema: z.ZodObject<{
     vertices: z.ZodArray<z.ZodNumber, "many">;
     dimension: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    dimension: number;
     vertices: number[];
-}, {
     dimension: number;
+}, {
     vertices: number[];
+    dimension: number;
 }>;
 export type Simplex = z.infer<typeof SimplexSchema>;
 export declare const SimplicialComplexSchema: z.ZodObject<{
@@ -260,25 +260,25 @@ export declare const SimplicialComplexSchema: z.ZodObject<{
         vertices: z.ZodArray<z.ZodNumber, "many">;
         dimension: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        dimension: number;
         vertices: number[];
-    }, {
         dimension: number;
+    }, {
         vertices: number[];
+        dimension: number;
     }>, "many">>;
     maxDimension: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     vertices: number[][];
-    maxDimension: number;
     simplices?: {
-        dimension: number;
         vertices: number[];
+        dimension: number;
     }[] | undefined;
+    maxDimension: number;
 }, {
     vertices: number[][];
     simplices?: {
-        dimension: number;
         vertices: number[];
+        dimension: number;
     }[] | undefined;
     maxDimension?: number | undefined;
 }>;
@@ -290,43 +290,43 @@ export declare const TopologyInputSchema: z.ZodObject<{
             vertices: z.ZodArray<z.ZodNumber, "many">;
             dimension: z.ZodNumber;
         }, "strip", z.ZodTypeAny, {
-            dimension: number;
             vertices: number[];
-        }, {
             dimension: number;
+        }, {
             vertices: number[];
+            dimension: number;
         }>, "many">>;
         maxDimension: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         vertices: number[][];
-        maxDimension: number;
         simplices?: {
-            dimension: number;
             vertices: number[];
+            dimension: number;
         }[] | undefined;
+        maxDimension: number;
     }, {
         vertices: number[][];
         simplices?: {
-            dimension: number;
             vertices: number[];
+            dimension: number;
         }[] | undefined;
         maxDimension?: number | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     complex: {
         vertices: number[][];
-        maxDimension: number;
         simplices?: {
-            dimension: number;
             vertices: number[];
+            dimension: number;
         }[] | undefined;
+        maxDimension: number;
     };
 }, {
     complex: {
         vertices: number[][];
         simplices?: {
-            dimension: number;
             vertices: number[];
+            dimension: number;
         }[] | undefined;
         maxDimension?: number | undefined;
     };
@@ -362,27 +362,27 @@ export declare const MemoryGateInputSchema: z.ZodObject<{
         reject: z.ZodDefault<z.ZodNumber>;
         warn: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        warn: number;
         reject: number;
+        warn: number;
     }, {
-        warn?: number | undefined;
         reject?: number | undefined;
+        warn?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     key: string;
     value?: unknown;
     existingVectors?: number[][] | undefined;
     thresholds?: {
-        warn: number;
         reject: number;
+        warn: number;
     } | undefined;
 }, {
     key: string;
     value?: unknown;
     existingVectors?: number[][] | undefined;
     thresholds?: {
-        warn?: number | undefined;
         reject?: number | undefined;
+        warn?: number | undefined;
     } | undefined;
 }>;
 export type MemoryGateInput = z.infer<typeof MemoryGateInputSchema>;

package/packages/@monomind/cli/dist/src/mcp-tools/hive-mind-tools.js

@@ -406,7 +406,11 @@ export const hiveMindTools = [
                         id: w,
                         type: agent?.agentType || 'worker',
                         status: agent?.status || 'unknown',
-                        currentTask: agent?.currentTask || null,
+                        // AgentRecord has no currentTask field — always null. Kept in the
+                        // response shape for API stability; was already dead before this
+                        // (the previous `as unknown as Record<string, unknown>` cast hid
+                        // that `agent?.currentTask` never matched a real field).
+                        currentTask: null,
                         tasksCompleted: agent?.taskCount || 0,
                     };
                 }),

package/packages/@monomind/cli/dist/src/mcp-tools/monograph-tools.js

@@ -744,7 +744,10 @@ async function computeCommitsBehind(repoPath) {
     const dbPath = getDbPath(repoPath);
     if (!_isValidDb(dbPath))
         return null;
-    const db = openDb(dbPath, { fileMustExist: true });
+    // openDb's fileMustExist option isn't in the currently-published
+    // @monoes/monograph release this CLI depends on — _isValidDb above is the
+    // real guard against openDb silently creating an empty DB at a missing path.
+    const db = openDb(dbPath);
     try {
         const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
         const lastCommit = meta?.value ?? null;
@@ -1761,9 +1764,15 @@ const monographInstallSkillsTool = {
         }
         // Load community data from graph
         const dbPath = getDbPath(repoPath);
+        // openDb's fileMustExist option isn't in the currently-published
+        // @monoes/monograph release this CLI depends on — check validity
+        // ourselves so a missing DB doesn't get silently auto-created empty.
+        if (!_isValidDb(dbPath)) {
+            return text('Graph not built yet. Run monograph_build first.');
+        }
         let db;
         try {
-            db = openDb(dbPath, { fileMustExist: true });
+            db = openDb(dbPath);
         }
         catch {
             return text('Graph not built yet. Run monograph_build first.');
@@ -1974,9 +1983,25 @@ const monographDeadCodeTool = {
         const cats = input.categories ?? ['dead-functions', 'orphan-files', 'stale-dist'];
         const result = {};
         const dbPath = getDbPath(repoPath);
+        // openDb's fileMustExist option isn't in the currently-published
+        // @monoes/monograph release this CLI depends on — check validity
+        // ourselves so a missing DB doesn't get silently auto-created empty.
+        if (!_isValidDb(dbPath)) {
+            return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
+        }
         let db = null;
         try {
-            db = openDb(dbPath, { fileMustExist: true });
+            db = openDb(dbPath);
+            // _isValidDb's size check can't distinguish a real index from an
+            // empty-but-schema-migrated DB (better-sqlite3 auto-creates + migrates
+            // on open, and other unguarded openDb() call sites in this file can
+            // create exactly that as a side effect of an unrelated tool call before
+            // monograph_build ever runs). Verify actual content post-open so this
+            // reports "never built" instead of a misleading "0 dead functions found".
+            const { count } = db.prepare('SELECT COUNT(*) as count FROM nodes').get();
+            if (count === 0) {
+                return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
+            }
         }
         catch {
             return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));