@pcircle/memesh 4.4.0 → 4.5.1

package/dist/transports/http/server.js

@@ -7,16 +7,16 @@ import { openDatabase, closeDatabase, getDatabase } from '../../db.js';
 import { remember, recallWithConflicts, forget, exportMemories, importMemories, learn } from '../../core/operations.js';
 import { KnowledgeGraph } from '../../knowledge-graph.js';
 import { logCapabilities, readConfig, updateConfig, detectCapabilities } from '../../core/config.js';
+import { languageValueError } from '../../core/output-language.js';
 import { computePatterns } from '../../core/patterns.js';
 import { computeAnalytics, computePmAnalytics } from '../../core/analytics.js';
 import { computeStats } from '../../core/stats.js';
 import { computeProjects } from '../../core/projects.js';
 import { computeGraph } from '../../core/graph.js';
-import { verifyAgentWork } from '../../core/verifier.js';
-import { RememberSchema as RememberBody, RecallSchema as RecallBody, ForgetSchema as ForgetBody, ExportSchema as ExportBody, ImportSchema as ImportBody, LearnSchema as LearnBody, VerifyAgentWorkSchema as VerifyBody, } from '../schemas.js';
-import { getUpdateCheck } from '../../core/version-check.js';
+import { RememberSchema as RememberBody, RecallSchema as RecallBody, ForgetSchema as ForgetBody, ExportSchema as ExportBody, ImportSchema as ImportBody, LearnSchema as LearnBody, } from '../schemas.js';
+import { checkForUpdate, getLastUpdateCheck, getUpdateCheck } from '../../core/version-check.js';
 import { getCurrentInstallChannel, getInstallChannelSupport } from '../../core/install-channel.js';
-import { getDbPath, getMemeshDirFromDbPath } from '../../core/paths.js';
+import { getDbPath, getMemeshDirFromDbPath, redactSecrets, redactUserPaths } from '../../core/paths.js';
 import { RETIRED_ROUTES } from './retired-routes.js';
 import fs from 'fs';
 import path from 'path';
@@ -25,12 +25,23 @@ const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)
 const packageRoot = path.dirname(packageJsonPath);
 const packageVersion = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version ?? '0.0.0';
 const app = express();
+export function isLoopbackRequest(req) {
+    const ip = req.ip ?? '';
+    return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+}
 const apiLimiter = rateLimit({
     windowMs: 15 * 60 * 1000,
     max: 100,
     standardHeaders: true,
     legacyHeaders: false,
-    message: 'Too many requests from this IP, please try again later.',
+    skip: (req) => isLoopbackRequest(req),
+    handler: (_req, res) => {
+        res.status(429).json({
+            success: false,
+            errorCode: 'rate.limited',
+            error: 'Too many requests in a short time. Wait a moment and try again.',
+        });
+    },
 });
 let remoteToken = null;
 const serverAuthRequired = new WeakMap();
@@ -97,6 +108,7 @@ function bearerAuth(req, res, next) {
     if (!remoteToken) {
         res.status(503).json({
             success: false,
+            errorCode: 'auth.not-configured',
             error: 'remote bearer auth not configured on this server',
         });
         return;
@@ -105,17 +117,17 @@ function bearerAuth(req, res, next) {
     const trimmed = header.trim();
     const wsIndex = trimmed.search(/\s/);
     if (wsIndex < 0 || trimmed.slice(0, wsIndex).toLowerCase() !== 'bearer') {
-        res.status(401).json({ success: false, error: 'Missing Authorization: Bearer <token>' });
+        res.status(401).json({ success: false, errorCode: 'auth.missing-bearer', error: 'Missing Authorization: Bearer <token>' });
         return;
     }
     const tokenPart = trimmed.slice(wsIndex + 1).trim();
     if (!tokenPart) {
-        res.status(401).json({ success: false, error: 'Missing Authorization: Bearer <token>' });
+        res.status(401).json({ success: false, errorCode: 'auth.missing-bearer', error: 'Missing Authorization: Bearer <token>' });
         return;
     }
     const presented = Buffer.from(tokenPart, 'utf8');
     if (!constantTimeEquals(presented, remoteToken)) {
-        res.status(401).json({ success: false, error: 'Invalid bearer token' });
+        res.status(401).json({ success: false, errorCode: 'auth.invalid-token', error: 'Invalid bearer token' });
         return;
     }
     next();
@@ -130,6 +142,7 @@ function payloadTooLargeHandler(err, _req, res, next) {
     if (e.type === 'entity.parse.failed' || (err instanceof SyntaxError && (e.status === 400 || e.statusCode === 400))) {
         res.status(400).json({
             success: false,
+            errorCode: 'validation.bad-body',
             error: 'Request body is not valid JSON.',
             hint: 'Send a JSON object with Content-Type: application/json.',
         });
@@ -140,6 +153,7 @@ function payloadTooLargeHandler(err, _req, res, next) {
         return next(err);
     res.status(413).json({
         success: false,
+        errorCode: 'payload.too-large',
         error: 'Request body exceeds the 1MB limit',
         code: 'PAYLOAD_TOO_LARGE',
         limit: '1mb',
@@ -179,25 +193,16 @@ app.get('/v1/health', (_req, res) => {
         if (message === 'Database not opened') {
             res.status(503).json({
                 success: false,
+                errorCode: 'server.internal',
                 error: 'Database not initialized',
                 details: 'MeMesh database failed to open at startup. Check server logs for details, or run "memesh doctor" to diagnose.',
             });
         }
         else {
-            res.status(500).json({ success: false, error: message });
+            res.status(500).json({ success: false, errorCode: 'server.internal', error: message });
         }
     }
 });
-function redactSecrets(input) {
-    return input
-        .replace(/sk-ant-[A-Za-z0-9_-]{20,}/g, 'sk-ant-***REDACTED***')
-        .replace(/sk-proj-[A-Za-z0-9_-]{20,}/g, 'sk-proj-***REDACTED***')
-        .replace(/sk-[A-Za-z0-9]{32,}/g, 'sk-***REDACTED***')
-        .replace(/ghp_[A-Za-z0-9]{30,}/g, 'ghp_***REDACTED***')
-        .replace(/gho_[A-Za-z0-9]{30,}/g, 'gho_***REDACTED***')
-        .replace(/AKIA[A-Z0-9]{16}/g, 'AKIA***REDACTED***')
-        .replace(/Bearer\s+[A-Za-z0-9._-]{20,}/gi, 'Bearer ***REDACTED***');
-}
 app.get('/v1/doctor', async (_req, res) => {
     try {
         const { runDoctor } = await import('../../core/doctor.js');
@@ -205,11 +210,11 @@ app.get('/v1/doctor', async (_req, res) => {
             packageRoot,
             packageVersion,
         });
-        const safe = JSON.parse(redactSecrets(JSON.stringify(result)));
+        const safe = JSON.parse(redactUserPaths(redactSecrets(JSON.stringify(result))));
         res.json({ success: true, data: safe });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 function requireJsonBody(req, res) {
@@ -217,6 +222,7 @@ function requireJsonBody(req, res) {
         return true;
     res.status(400).json({
         success: false,
+        errorCode: 'validation.bad-body',
         error: 'No JSON body was parsed from this request.',
         hint: 'Send the payload with Content-Type: application/json.',
     });
@@ -229,27 +235,29 @@ function handlePost(schema, req, res, handler) {
     if (!parsed.success) {
         res.status(400).json({
             success: false,
+            errorCode: 'validation.bad-body',
             error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
         });
         return;
     }
-    Promise.resolve(handler(parsed.data))
+    Promise.resolve()
+        .then(() => handler(parsed.data))
         .then((data) => res.json({ success: true, data }))
-        .catch((err) => res.status(400).json({ success: false, error: err instanceof Error ? err.message : String(err) }));
+        .catch((err) => res.status(400).json({ success: false, errorCode: 'operation.failed', error: err instanceof Error ? err.message : String(err) }));
 }
 function handleGet(res, produce) {
     Promise.resolve()
         .then(produce)
         .then((data) => res.json({ success: true, data }))
-        .catch((err) => res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) }));
+        .catch((err) => res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) }));
 }
-app.post('/v1/remember', (req, res) => handlePost(RememberBody, req, res, remember));
+app.post('/v1/remember', (req, res) => handlePost(RememberBody, req, res, (data) => remember({ ...data, sourceHost: 'http' })));
 app.post('/v1/recall', async (req, res) => {
     if (!requireJsonBody(req, res))
         return;
     const parsed = RecallBody.safeParse(req.body);
     if (!parsed.success) {
-        res.status(400).json({ success: false, error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ') });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-body', error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ') });
         return;
     }
     try {
@@ -257,27 +265,46 @@ app.post('/v1/recall', async (req, res) => {
         res.json({ success: true, data: conflicts.length > 0 ? { entities, conflicts } : entities });
     }
     catch (err) {
-        res.status(400).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(400).json({ success: false, errorCode: 'operation.failed', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.post('/v1/forget', (req, res) => handlePost(ForgetBody, req, res, forget));
 app.post('/v1/consolidate', (_req, res) => {
-    res.status(410).json({ success: false, error: RETIRED_ROUTES['/v1/consolidate'] });
+    res.status(410).json({ success: false, errorCode: 'route.retired', error: RETIRED_ROUTES['/v1/consolidate'] });
 });
 app.post('/v1/export', (req, res) => handlePost(ExportBody, req, res, exportMemories));
 app.post('/v1/import', (req, res) => handlePost(ImportBody, req, res, importMemories));
-app.post('/v1/learn', (req, res) => handlePost(LearnBody, req, res, learn));
-app.post('/v1/verify', (req, res) => handlePost(VerifyBody, req, res, verifyAgentWork));
+app.post('/v1/learn', (req, res) => handlePost(LearnBody, req, res, (data) => learn({ ...data, sourceHost: 'http' })));
+app.post('/v1/verify', (_req, res) => {
+    res.status(410).json({ success: false, errorCode: 'route.retired', error: RETIRED_ROUTES['/v1/verify'] });
+});
+const API_KEY_MASK = '***';
 function maskLlmSecrets(obj) {
     const masked = { ...obj };
     if (masked.llm?.apiKey) {
-        masked.llm = { ...masked.llm, apiKey: '***' };
+        masked.llm = { ...masked.llm, apiKey: API_KEY_MASK };
     }
     if (Array.isArray(masked.llmFallbacks) && masked.llmFallbacks.length > 0) {
-        masked.llmFallbacks = masked.llmFallbacks.map(fb => fb?.apiKey ? { ...fb, apiKey: '***' } : fb);
+        masked.llmFallbacks = masked.llmFallbacks.map(fb => fb?.apiKey ? { ...fb, apiKey: API_KEY_MASK } : fb);
     }
     return masked;
 }
+function preserveFallbackApiKeys(incoming, stored) {
+    return incoming.map((entry) => {
+        const { keepKeyFrom, ...clean } = entry;
+        if (clean.apiKey === API_KEY_MASK)
+            delete clean.apiKey;
+        if (clean.apiKey)
+            return clean;
+        if (typeof keepKeyFrom === 'number' && stored && keepKeyFrom >= 0 && keepKeyFrom < stored.length) {
+            const src = stored[keepKeyFrom];
+            if (src && src.provider === clean.provider && src.apiKey) {
+                return { ...clean, apiKey: src.apiKey };
+            }
+        }
+        return clean;
+    });
+}
 app.get('/v1/config', (_req, res) => {
     try {
         const config = readConfig();
@@ -285,7 +312,7 @@ app.get('/v1/config', (_req, res) => {
         res.json({ success: true, data: { config: maskLlmSecrets(config), capabilities: maskLlmSecrets(caps) } });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 const ConfigBody = z.object({
@@ -301,11 +328,16 @@ const ConfigBody = z.object({
         provider: z.enum(['anthropic', 'openai', 'ollama']),
         model: z.string().optional(),
         apiKey: z.string().optional(),
+        keepKeyFrom: z.number().int().nonnegative().nullable().optional(),
     })).optional(),
     autoCapture: z.boolean().optional(),
     sessionLimit: z.number().int().min(1).max(100).optional(),
-    enableAgenticOrchestration: z.boolean().optional(),
     autoUpdate: z.enum(['off', 'patch', 'minor', 'major']).optional(),
+    language: z.string().trim().min(1).max(60)
+        .refine((v) => languageValueError(v) === null, {
+        message: 'language must not contain line breaks or other control characters',
+    })
+        .optional(),
     setupCompleted: z.boolean().optional(),
 }).strip();
 app.post('/v1/config', async (req, res) => {
@@ -313,29 +345,34 @@ app.post('/v1/config', async (req, res) => {
         return;
     const parsed = ConfigBody.safeParse(req.body);
     if (!parsed.success) {
-        res.status(400).json({ success: false, error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ') });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-body', error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ') });
         return;
     }
     try {
         const before = readConfig();
-        const updated = updateConfig(parsed.data);
-        const llmChanged = parsed.data.llm !== undefined &&
-            (before.llm?.provider !== updated.llm?.provider ||
-                before.llm?.apiKey !== updated.llm?.apiKey);
-        if (llmChanged) {
-            const { resetEmbeddingState } = await import('../../core/embedder.js');
-            resetEmbeddingState();
+        if (parsed.data.llm && parsed.data.llm.apiKey === API_KEY_MASK) {
+            if (before.llm && before.llm.provider === parsed.data.llm.provider && before.llm.apiKey) {
+                parsed.data.llm.apiKey = before.llm.apiKey;
+            }
+            else {
+                delete parsed.data.llm.apiKey;
+            }
+        }
+        if (parsed.data.llmFallbacks) {
+            parsed.data.llmFallbacks = preserveFallbackApiKeys(parsed.data.llmFallbacks, before.llmFallbacks);
         }
+        const updated = updateConfig(parsed.data);
         res.json({ success: true, data: maskLlmSecrets(updated) });
     }
     catch (err) {
-        res.status(400).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(400).json({ success: false, errorCode: 'operation.failed', error: err instanceof Error ? err.message : String(err) });
     }
 });
 const ConfigTestBody = z.object({
     provider: z.enum(['anthropic', 'openai', 'ollama']),
     apiKey: z.string().max(500).optional(),
     host: z.string().max(500).optional(),
+    fallbackIndex: z.number().int().nonnegative().optional(),
 });
 app.post('/v1/config/test', async (req, res) => {
     if (!requireJsonBody(req, res))
@@ -344,17 +381,23 @@ app.post('/v1/config/test', async (req, res) => {
     if (!parsed.success) {
         res.status(400).json({
             success: false,
+            errorCode: 'validation.bad-body',
             error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
         });
         return;
     }
     try {
         const { probeProvider } = await import('../../core/llm-validator.js');
-        const { provider, host } = parsed.data;
+        const { provider, host, fallbackIndex } = parsed.data;
         let { apiKey } = parsed.data;
         if (!apiKey && (provider === 'anthropic' || provider === 'openai')) {
             const existing = readConfig();
-            if (existing.llm?.provider === provider && existing.llm.apiKey) {
+            if (typeof fallbackIndex === 'number') {
+                const fb = existing.llmFallbacks?.[fallbackIndex];
+                if (fb && fb.provider === provider && fb.apiKey)
+                    apiKey = fb.apiKey;
+            }
+            else if (existing.llm?.provider === provider && existing.llm.apiKey) {
                 apiKey = existing.llm.apiKey;
             }
         }
@@ -362,7 +405,7 @@ app.post('/v1/config/test', async (req, res) => {
         res.json({ success: true, data: result });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.get('/v1/update-status', async (req, res) => {
@@ -396,7 +439,7 @@ app.get('/v1/update-status', async (req, res) => {
         });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.get('/v1/graph', (_req, res) => handleGet(res, () => computeGraph(getDatabase())));
@@ -415,7 +458,7 @@ app.post('/v1/demo/seed', async (_req, res) => {
         res.json({ success: true, data });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.post('/v1/demo/reset', async (_req, res) => {
@@ -425,7 +468,7 @@ app.post('/v1/demo/reset', async (_req, res) => {
         res.json({ success: true, data });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.get('/v1/projects', (_req, res) => handleGet(res, () => computeProjects(getDatabase())));
@@ -437,7 +480,7 @@ app.get('/v1/telemetry', async (req, res) => {
     try {
         const parsed = TelemetryQuerySchema.safeParse(req.query);
         if (!parsed.success) {
-            res.status(400).json({ success: false, error: parsed.error.issues.map(i => i.message).join('; ') });
+            res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: parsed.error.issues.map(i => i.message).join('; ') });
             return;
         }
         const { summariseTelemetry } = await import('../../core/llm-telemetry.js');
@@ -445,7 +488,7 @@ app.get('/v1/telemetry', async (req, res) => {
         res.json({ success: true, data: { window_days: parsed.data.window, summaries } });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 const DreamProposalsQuerySchema = z.object({
@@ -455,7 +498,7 @@ app.get('/v1/dream/proposals', (req, res) => {
     try {
         const parsed = DreamProposalsQuerySchema.safeParse(req.query);
         if (!parsed.success) {
-            res.status(400).json({ success: false, error: parsed.error.issues.map(i => i.message).join('; ') });
+            res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: parsed.error.issues.map(i => i.message).join('; ') });
             return;
         }
         const status = parsed.data.status;
@@ -465,22 +508,22 @@ app.get('/v1/dream/proposals', (req, res) => {
                 ? [...listProposals(db, 'pending'), ...listProposals(db, 'applied'), ...listProposals(db, 'rejected')]
                 : listProposals(db, status);
             res.json({ success: true, data: rows });
-        }).catch((err) => res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) }));
+        }).catch((err) => res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) }));
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.get('/v1/dream/proposals/:id', (req, res) => {
     const id = parseInt(req.params.id, 10);
     if (!Number.isInteger(id) || id < 1) {
-        res.status(400).json({ success: false, error: 'invalid id' });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: 'invalid id' });
         return;
     }
     try {
         const row = getDatabase().prepare('SELECT id, project, cluster_key, source_ids, proposed_digest, llm_model, prompt_version, status, reason, created_at, reviewed_at FROM dream_proposals WHERE id = ?').get(id);
         if (!row) {
-            res.status(404).json({ success: false, error: `proposal #${id} not found` });
+            res.status(404).json({ success: false, errorCode: 'resource.not-found', error: `proposal #${id} not found` });
             return;
         }
         let digest = null;
@@ -496,7 +539,7 @@ app.get('/v1/dream/proposals/:id', (req, res) => {
         res.json({ success: true, data: { ...row, proposed_digest: digest, source_ids: sourceIds } });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 const DreamRunBody = z.object({
@@ -510,52 +553,60 @@ app.post('/v1/dream/run', async (req, res) => {
     if (!parsed.success) {
         res.status(400).json({
             success: false,
+            errorCode: 'validation.bad-body',
             error: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
         });
         return;
     }
     try {
         const { runDreamer } = await import('../../core/dreamer.js');
-        const cfg = readConfig();
-        if (!cfg.llm) {
+        const caps = detectCapabilities();
+        const llm = caps.llm;
+        if (!llm) {
             res.status(400).json({
                 success: false,
+                errorCode: 'llm.not-configured',
                 error: 'No LLM configured — dream run requires Smart Mode. Configure a provider in Settings.',
             });
             return;
         }
-        const result = await runDreamer(getDatabase(), cfg.llm, {
+        const result = await runDreamer(getDatabase(), llm, {
             project: parsed.data.project,
             windowDays: parsed.data.windowDays,
             maxLlmCalls: parsed.data.maxLlmCalls,
-            fallbacks: cfg.llmFallbacks,
+            fallbacks: caps.llmFallbacks,
             validateBeforeStage: parsed.data.validate,
         });
         res.json({ success: true, data: result });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.post('/v1/dream/proposals/:id/accept', async (req, res) => {
     const id = parseInt(req.params.id, 10);
     if (!Number.isInteger(id) || id < 1) {
-        res.status(400).json({ success: false, error: 'invalid id' });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: 'invalid id' });
         return;
     }
+    let NothingToClaim;
     try {
-        const { applyProposal } = await import('../../core/dreamer.js');
+        const dreamer = await import('../../core/dreamer.js');
+        NothingToClaim = dreamer.NothingToClaimError;
         const kg = new KnowledgeGraph(getDatabase());
-        const result = applyProposal(getDatabase(), id, kg);
+        const result = dreamer.applyProposal(getDatabase(), id, kg);
         res.json({ success: true, data: result });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        if (/not found or not pending/.test(msg)) {
-            res.status(404).json({ success: false, error: msg });
+        if (NothingToClaim && err instanceof NothingToClaim) {
+            res.status(400).json({ success: false, errorCode: 'operation.failed', error: msg });
+        }
+        else if (/not found or not pending/.test(msg)) {
+            res.status(404).json({ success: false, errorCode: 'resource.not-found', error: msg });
         }
         else {
-            res.status(500).json({ success: false, error: msg });
+            res.status(500).json({ success: false, errorCode: 'server.internal', error: msg });
         }
     }
 });
@@ -565,12 +616,12 @@ const RejectBodySchema = z.object({
 app.post('/v1/dream/proposals/:id/reject', async (req, res) => {
     const id = parseInt(req.params.id, 10);
     if (!Number.isInteger(id) || id < 1) {
-        res.status(400).json({ success: false, error: 'invalid id' });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: 'invalid id' });
         return;
     }
     const parsed = RejectBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
-        res.status(400).json({ success: false, error: parsed.error.issues.map(i => i.message).join('; ') });
+        res.status(400).json({ success: false, errorCode: 'validation.bad-body', error: parsed.error.issues.map(i => i.message).join('; ') });
         return;
     }
     try {
@@ -581,10 +632,10 @@ app.post('/v1/dream/proposals/:id/reject', async (req, res) => {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (/not found or not pending/.test(msg)) {
-            res.status(404).json({ success: false, error: msg });
+            res.status(404).json({ success: false, errorCode: 'resource.not-found', error: msg });
         }
         else {
-            res.status(500).json({ success: false, error: msg });
+            res.status(500).json({ success: false, errorCode: 'server.internal', error: msg });
         }
     }
 });
@@ -597,7 +648,7 @@ app.get('/v1/entities', (req, res) => {
     try {
         const parsed = EntitiesQuerySchema.safeParse(req.query);
         if (!parsed.success) {
-            res.status(400).json({ success: false, error: `Invalid query: ${parsed.error.message}` });
+            res.status(400).json({ success: false, errorCode: 'validation.bad-param', error: `Invalid query: ${parsed.error.message}` });
             return;
         }
         const { type: typeFilter, limit, status } = parsed.data;
@@ -610,7 +661,7 @@ app.get('/v1/entities', (req, res) => {
         res.json({ success: true, data: entities });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 app.get('/v1/entities/:name', (req, res) => {
@@ -619,13 +670,13 @@ app.get('/v1/entities/:name', (req, res) => {
         const kg = new KnowledgeGraph(db);
         const entity = kg.getEntity(req.params.name);
         if (!entity) {
-            res.status(404).json({ success: false, error: `Entity "${req.params.name}" not found` });
+            res.status(404).json({ success: false, errorCode: 'resource.not-found', error: `Entity "${req.params.name}" not found` });
             return;
         }
         res.json({ success: true, data: entity });
     }
     catch (err) {
-        res.status(500).json({ success: false, error: err instanceof Error ? err.message : String(err) });
+        res.status(500).json({ success: false, errorCode: 'server.internal', error: err instanceof Error ? err.message : String(err) });
     }
 });
 const HOST = process.env.MEMESH_HTTP_HOST || '127.0.0.1';
@@ -645,6 +696,7 @@ function isLoopbackHost(host) {
 app.use((req, res) => {
     res.status(404).json({
         success: false,
+        errorCode: 'route.not-found',
         code: 'NOT_FOUND',
         error: `No route for ${req.method} ${req.path}`,
     });
@@ -655,6 +707,10 @@ export function startServer(host = HOST, port = PORT, opts) {
     if (!allowRemote && isRemote) {
         throw new Error(`Refusing to bind MeMesh HTTP server to non-loopback host "${host}" without explicit remote access opt-in. Use --allow-remote or MEMESH_HTTP_ALLOW_REMOTE=true.`);
     }
+    if (allowRemote && !isRemote) {
+        process.stderr.write(`MeMesh HTTP: --allow-remote has no effect on loopback host "${host}" — the server stays local ` +
+            'and no bearer token is generated. Add --host <address> to bind somewhere reachable.\n');
+    }
     if (isRemote) {
         const { token, freshlyCreated } = loadOrCreateRemoteToken();
         remoteToken = token;
@@ -694,16 +750,39 @@ export function startServer(host = HOST, port = PORT, opts) {
         throw new Error(`Database initialization failed: ${message}`, { cause: err });
     }
     logCapabilities();
+    const injectedUpdateSeam = Boolean(opts?.updateCheckImpl || opts?.lastUpdateCheckImpl);
+    const updateCheckWanted = opts?.autoUpdateCheck === true || injectedUpdateSeam;
+    if (updateCheckWanted && !process.env.MEMESH_SKIP_UPDATE_CHECK) {
+        void (async () => {
+            const readLast = opts?.lastUpdateCheckImpl ?? getLastUpdateCheck;
+            const refresh = opts?.updateCheckImpl ?? checkForUpdate;
+            const cached = readLast(packageVersion);
+            if (cached && (cached.freshness === 'fresh' || cached.freshness === 'cached'))
+                return;
+            await refresh(packageVersion);
+        })().catch(() => { });
+    }
     const server = app.listen(port, host, () => {
         const addr = server.address();
         if (addr && typeof addr === 'object') {
             console.log(`MeMesh HTTP server running at http://${addr.address}:${addr.port}`);
             console.log(`MeMesh dashboard: http://${addr.address}:${addr.port}/dashboard`);
         }
+    });
+    server.on('error', (err) => {
+        const where = `${host}:${port}`;
+        if (err.code === 'EADDRINUSE') {
+            console.error(`MeMesh: cannot start — ${where} is already in use.`);
+            console.error(`MeMesh: stop whatever is listening there, or pick another port with --port <n>.`);
+        }
+        else if (err.code === 'EACCES') {
+            console.error(`MeMesh: cannot start — not permitted to bind ${where}.`);
+            console.error(`MeMesh: ports below 1024 need elevated privileges; pick a port above 1024 with --port <n>.`);
+        }
         else {
-            console.log(`MeMesh HTTP server running at http://${host}:${port}`);
-            console.log(`MeMesh dashboard: http://${host}:${port}/dashboard`);
+            console.error(`MeMesh: cannot start on ${where} — ${err.message}`);
         }
+        process.exit(1);
     });
     serverAuthRequired.set(server, isRemote);
     return server;
@@ -713,7 +792,14 @@ export function __setRemoteTokenForTest(value) {
 }
 const isMain = process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'));
 if (isMain || process.argv[1]?.endsWith('memesh-http')) {
-    const server = startServer();
+    let server;
+    try {
+        server = startServer();
+    }
+    catch (err) {
+        console.error(`MeMesh: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
     function shutdown() {
         server.close();
         try {