@pcircle/memesh 4.4.0 → 4.5.0

package/dist/transports/http/server.js

@@ -7,6 +7,7 @@ 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';
@@ -14,7 +15,7 @@ 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 { checkForUpdate, getLastUpdateCheck, getUpdateCheck } from '../../core/version-check.js';
 import { getCurrentInstallChannel, getInstallChannelSupport } from '../../core/install-channel.js';
 import { getDbPath, getMemeshDirFromDbPath } from '../../core/paths.js';
 import { RETIRED_ROUTES } from './retired-routes.js';
@@ -25,12 +26,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 +109,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 +118,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 +143,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 +154,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,12 +194,13 @@ 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 });
         }
     }
 });
@@ -209,7 +225,7 @@ app.get('/v1/doctor', async (_req, res) => {
         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 +233,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,19 +246,20 @@ 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))
         .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/recall', async (req, res) => {
@@ -249,7 +267,7 @@ app.post('/v1/recall', async (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 +275,44 @@ 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));
+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 +320,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 +336,17 @@ 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 +354,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 +390,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 +414,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 +448,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 +467,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 +477,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 +489,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 +497,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 +507,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 +517,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 +548,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,6 +562,7 @@ 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;
@@ -520,6 +573,7 @@ app.post('/v1/dream/run', async (req, res) => {
         if (!cfg.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;
@@ -534,13 +588,13 @@ app.post('/v1/dream/run', 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.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;
     }
     try {
@@ -552,10 +606,10 @@ app.post('/v1/dream/proposals/:id/accept', 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 });
         }
     }
 });
@@ -565,12 +619,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 +635,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 +651,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 +664,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 +673,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 +699,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}`,
     });
@@ -694,6 +749,18 @@ 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') {