@jagilber-org/index-server 1.26.11 → 1.27.2

package/dist/server/sdkServer.js

@@ -21,6 +21,7 @@ const registry_1 = require("./registry");
 const zod_1 = require("zod");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const mcpLogBridge_1 = require("../services/mcpLogBridge");
+const logger_1 = require("../services/logger");
 const handshakeManager_1 = require("./handshakeManager");
 const transportFactory_1 = require("./transportFactory");
 const mcpReadOnlySurfaces_1 = require("./mcpReadOnlySurfaces");
@@ -205,6 +206,8 @@ function createSdkServer(ServerClass) {
         const args = p.arguments || {};
         if (name === 'health_check')
             (0, handshakeManager_1.record)('tools_call_health');
+        const __callStart = Date.now();
+        (0, logger_1.logInfo)('[rpc] tools/call', { tool: name, id: req?.id ?? null });
         try {
             if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                 process.stderr.write(`[rpc] call method=tools/call tool=${name} id=${req?.id ?? 'n/a'}\n`);
@@ -216,9 +219,11 @@ function createSdkServer(ServerClass) {
         }
         try {
             const result = await Promise.resolve(handler(args));
+            const bytes = Buffer.byteLength(JSON.stringify(result), 'utf8');
+            (0, logger_1.logInfo)('[rpc] tools/call ok', { tool: name, ms: Date.now() - __callStart, bytes });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${Buffer.byteLength(JSON.stringify(result), 'utf8')}\n`);
+                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${bytes}\n`);
             }
             catch { /* ignore */ }
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -226,7 +231,10 @@ function createSdkServer(ServerClass) {
         catch (e) {
             const code = e?.code;
             const sem = e?.__semantic === true;
+            const msgRaw = e instanceof Error ? e.message : String(e);
+            const stack = e instanceof Error ? e.stack : undefined;
             if (Number.isSafeInteger(code)) {
+                (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code, semantic: sem, message: msgRaw, stack });
                 try {
                     if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                         process.stderr.write(`[rpc] tool_error_passthru tool=${name} code=${code} semantic=${sem ? '1' : '0'} msg=${e?.message || ''}\n`);
@@ -234,13 +242,13 @@ function createSdkServer(ServerClass) {
                 catch { /* ignore */ }
                 throw e;
             }
-            const msg = e instanceof Error ? e.message : String(e);
+            (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code: code ?? null, message: msgRaw, stack });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msg.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
+                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msgRaw.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
             }
             catch { /* ignore */ }
-            throw { code: -32603, message: 'Tool execution failed', data: { message: msg, method: name } };
+            throw { code: -32603, message: 'Tool execution failed', data: { message: msgRaw, method: name } };
         }
     });
     // Lightweight ping handler (simple reachability / latency measurement)

package/dist/services/embeddingService.d.ts

@@ -58,6 +58,8 @@ export declare function embedText(text: string, modelName: string, cacheDir: str
  */
 export declare function checkModelReadiness(modelName: string, cacheDir: string, localOnly: boolean): {
     ready: boolean;
+    cached: boolean;
+    modelPath: string;
     message?: string;
 };
 /** Signature for the embed function (injectable for testing). */

package/dist/services/embeddingService.js

@@ -187,22 +187,34 @@ async function embedText(text, modelName, cacheDir, device = 'cpu', localOnly =
  * @returns Object with `ready` flag and optional remediation `message`.
  */
 function checkModelReadiness(modelName, cacheDir, localOnly) {
-    if (!localOnly) {
-        return { ready: true }; // Model can be downloaded on demand
-    }
     // HuggingFace transformers caches models as: models--<org>--<name>
     const modelDirName = `models--${modelName.replace(/\//g, '--')}`;
     const modelPath = path_1.default.join(cacheDir, modelDirName);
+    let cached = false;
     try {
         if (fs_1.default.existsSync(modelPath) && fs_1.default.readdirSync(modelPath).length > 0) {
-            return { ready: true };
+            cached = true;
         }
     }
     catch {
         // Directory doesn't exist or can't be read
     }
+    if (cached) {
+        return { ready: true, cached: true, modelPath };
+    }
+    if (!localOnly) {
+        return {
+            ready: true,
+            cached: false,
+            modelPath,
+            message: `Embedding model '${modelName}' is not yet cached. ` +
+                `It will be downloaded to '${cacheDir}' on first compute (~25 MB).`,
+        };
+    }
     return {
         ready: false,
+        cached: false,
+        modelPath,
         message: `Embedding model '${modelName}' not found in cache (${cacheDir}). ` +
             `LOCAL_ONLY is enabled, so the model cannot be downloaded automatically. ` +
             `To fix: set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=0 to allow download, ` +

package/dist/services/embeddingTrigger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+/** Whether auto-compute is enabled given current env / runtime config. */
+export declare function autoEmbedEnabled(): boolean;
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+export declare function triggerEmbeddingComputeAfterImport(reason: string): Promise<{
+    triggered: boolean;
+    reason?: string;
+    entries?: number;
+    ms?: number;
+}>;
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+export declare function scheduleEmbeddingComputeAfterImport(reason: string): void;

package/dist/services/embeddingTrigger.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoEmbedEnabled = autoEmbedEnabled;
+exports.triggerEmbeddingComputeAfterImport = triggerEmbeddingComputeAfterImport;
+exports.scheduleEmbeddingComputeAfterImport = scheduleEmbeddingComputeAfterImport;
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const indexContext_1 = require("./indexContext");
+const embeddingService_1 = require("./embeddingService");
+const logger_1 = require("./logger");
+const envUtils_1 = require("../utils/envUtils");
+let lastTriggerAt = 0;
+/** Whether auto-compute is enabled given current env / runtime config. */
+function autoEmbedEnabled() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    if (!cfg.semantic.enabled)
+        return false;
+    const raw = process.env.INDEX_SERVER_AUTO_EMBED_ON_IMPORT;
+    // Default ON when semantic is enabled; explicit '0' / 'false' opts out.
+    if (raw === undefined)
+        return true;
+    return (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_AUTO_EMBED_ON_IMPORT', true);
+}
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+async function triggerEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled()) {
+        return { triggered: false, reason: 'auto-embed disabled or semantic disabled' };
+    }
+    // Light debounce — coalesce rapid back-to-back imports.
+    const now = Date.now();
+    if (now - lastTriggerAt < 1000) {
+        return { triggered: false, reason: 'debounced' };
+    }
+    lastTriggerAt = now;
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    const sem = cfg.semantic;
+    const start = Date.now();
+    try {
+        (0, indexContext_1.ensureLoaded)();
+        const state = (0, indexContext_1.getIndexState)();
+        if (!state.list || state.list.length === 0) {
+            (0, logger_1.logInfo)(`[embedding-trigger] Skipped (no instructions loaded) reason=${reason}`);
+            return { triggered: false, reason: 'no instructions loaded' };
+        }
+        (0, logger_1.logInfo)(`[embedding-trigger] Starting auto-compute reason=${reason} entries=${state.list.length}`);
+        await (0, embeddingService_1.getInstructionEmbeddings)(state.list, state.hash, sem.embeddingPath, sem.model, sem.cacheDir, sem.device, sem.localOnly);
+        const ms = Date.now() - start;
+        (0, logger_1.logInfo)(`[embedding-trigger] Auto-compute complete reason=${reason} entries=${state.list.length} ms=${ms}`);
+        return { triggered: true, entries: state.list.length, ms };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Use WARN (not ERROR) so we don't escalate transient model-load issues to ERROR-level paging.
+        (0, logger_1.logWarn)(`[embedding-trigger] Auto-compute failed reason=${reason}: ${msg}`);
+        return { triggered: false, reason: `failed: ${msg}` };
+    }
+}
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+function scheduleEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled())
+        return;
+    setImmediate(() => {
+        triggerEmbeddingComputeAfterImport(reason).catch(() => { });
+    });
+}

package/dist/services/eventBuffer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-process ring buffer of recent log events at WARN/ERROR severity.
+ *
+ * Surfaces operationally-meaningful events to the admin dashboard so operators
+ * do not have to tail server logs. Read-only, bounded; never persists to disk.
+ *
+ * Capacity defaults to 500. The logger emits records via `recordEvent()` only
+ * for WARN or ERROR levels so that volume on healthy systems is negligible.
+ *
+ * Constitution alignment: OB-1, OB-3, OB-4, OB-5 (structured, severity-visible).
+ */
+export type EventLevel = 'WARN' | 'ERROR';
+export interface BufferedEvent {
+    /** Monotonically increasing per-process id (used for unread counts). */
+    id: number;
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** Severity. */
+    level: EventLevel;
+    /** Message; prefix `[module]` is preserved. */
+    msg: string;
+    /** Optional stack/detail snippet. */
+    detail?: string;
+    /** Process id of emitter. */
+    pid?: number;
+}
+/** Emit a WARN/ERROR event into the buffer. Called by the logger. */
+export declare function recordEvent(level: EventLevel, msg: string, detail?: string, pid?: number): void;
+/** List recent events (most recent last). */
+export declare function listEvents(opts?: {
+    sinceId?: number;
+    level?: EventLevel;
+    limit?: number;
+}): BufferedEvent[];
+/** Compute new-event counts since the supplied id (used for the dashboard counter bubble). */
+export declare function eventCounts(sinceId?: number): {
+    warn: number;
+    error: number;
+    total: number;
+    latestId: number;
+};
+/** Clear the buffer (used by `Mark all read` and tests). */
+export declare function clearEvents(): void;
+/** Test-only helper. */
+export declare function _eventBufferSize(): number;

package/dist/services/eventBuffer.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * In-process ring buffer of recent log events at WARN/ERROR severity.
+ *
+ * Surfaces operationally-meaningful events to the admin dashboard so operators
+ * do not have to tail server logs. Read-only, bounded; never persists to disk.
+ *
+ * Capacity defaults to 500. The logger emits records via `recordEvent()` only
+ * for WARN or ERROR levels so that volume on healthy systems is negligible.
+ *
+ * Constitution alignment: OB-1, OB-3, OB-4, OB-5 (structured, severity-visible).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordEvent = recordEvent;
+exports.listEvents = listEvents;
+exports.eventCounts = eventCounts;
+exports.clearEvents = clearEvents;
+exports._eventBufferSize = _eventBufferSize;
+const DEFAULT_CAPACITY = 500;
+class EventRing {
+    buf = [];
+    nextId = 1;
+    capacity = DEFAULT_CAPACITY;
+    /** Read the configured capacity (env: INDEX_SERVER_EVENT_BUFFER_SIZE, min 50, max 5000). */
+    resolveCapacity() {
+        const raw = process.env.INDEX_SERVER_EVENT_BUFFER_SIZE;
+        if (!raw)
+            return DEFAULT_CAPACITY;
+        const n = parseInt(raw, 10);
+        if (!Number.isFinite(n) || n <= 0)
+            return DEFAULT_CAPACITY;
+        return Math.min(5000, Math.max(50, n));
+    }
+    add(level, msg, detail, pid) {
+        // Refresh capacity lazily so runtime changes take effect.
+        const cap = this.resolveCapacity();
+        if (cap !== this.capacity) {
+            this.capacity = cap;
+            if (this.buf.length > cap)
+                this.buf.splice(0, this.buf.length - cap);
+        }
+        const evt = {
+            id: this.nextId++,
+            ts: new Date().toISOString(),
+            level,
+            msg,
+            pid,
+        };
+        if (detail)
+            evt.detail = detail.length > 4096 ? detail.slice(0, 4096) + '…' : detail;
+        this.buf.push(evt);
+        if (this.buf.length > this.capacity)
+            this.buf.shift();
+    }
+    /** List events newer than `sinceId` (exclusive), optionally filtered by level. */
+    list(opts = {}) {
+        const sinceId = opts.sinceId ?? 0;
+        const limit = Math.min(1000, Math.max(1, opts.limit ?? 200));
+        const filtered = [];
+        for (let i = this.buf.length - 1; i >= 0 && filtered.length < limit; i--) {
+            const e = this.buf[i];
+            if (e.id <= sinceId)
+                break;
+            if (opts.level && e.level !== opts.level)
+                continue;
+            filtered.push(e);
+        }
+        return filtered.reverse();
+    }
+    /** Counts of WARN and ERROR events newer than `sinceId`. */
+    counts(sinceId = 0) {
+        let warn = 0, error = 0;
+        for (const e of this.buf) {
+            if (e.id <= sinceId)
+                continue;
+            if (e.level === 'WARN')
+                warn++;
+            else if (e.level === 'ERROR')
+                error++;
+        }
+        const latestId = this.buf.length ? this.buf[this.buf.length - 1].id : 0;
+        return { warn, error, total: warn + error, latestId };
+    }
+    clear() {
+        this.buf = [];
+    }
+    /** Test-only: current size. */
+    size() { return this.buf.length; }
+}
+const ring = new EventRing();
+/** Emit a WARN/ERROR event into the buffer. Called by the logger. */
+function recordEvent(level, msg, detail, pid) {
+    ring.add(level, msg, detail, pid);
+}
+/** List recent events (most recent last). */
+function listEvents(opts) {
+    return ring.list(opts);
+}
+/** Compute new-event counts since the supplied id (used for the dashboard counter bubble). */
+function eventCounts(sinceId) {
+    return ring.counts(sinceId);
+}
+/** Clear the buffer (used by `Mark all read` and tests). */
+function clearEvents() {
+    ring.clear();
+}
+/** Test-only helper. */
+function _eventBufferSize() {
+    return ring.size();
+}

package/dist/services/handlers/instructions.import.js

@@ -15,6 +15,12 @@ const ownershipService_1 = require("../ownershipService");
 const instructionRecordValidation_1 = require("../instructionRecordValidation");
 const instructionRecordValidation_2 = require("../instructionRecordValidation");
 const auditLog_1 = require("../auditLog");
+const logger_1 = require("../logger");
+// Structured WARN without auto-attached call stack: the log-hygiene gate
+// (scripts/crawl-logs.mjs) treats WARN-with-stack as a budget violation
+// (max-stack-warn=5). Use log('WARN', ...) directly with serialized detail
+// so per-entry import rejections stay structured but stackless.
+const warnStruct = (msg, detail) => (0, logger_1.log)('WARN', msg, { detail: detail === undefined ? undefined : typeof detail === 'string' ? detail : JSON.stringify(detail) });
 const runtimeConfig_1 = require("../../config/runtimeConfig");
 const manifestManager_1 = require("../manifestManager");
 const instructions_shared_1 = require("./instructions.shared");
@@ -44,48 +50,77 @@ function parseInlineEntries(rawEntries) {
 (0, registry_1.registerHandler)('index_import', (0, instructions_shared_1.guard)('index_import', async (p) => {
     let entries;
     const mode = p.mode || 'skip';
+    // Source-type breadcrumb for observability: agents currently get a silent
+    // { error: ... } back on top-level failures (path-blocked, parse errors,
+    // missing files). Without these explicit WARN logs the only signal is the
+    // RPC response, which dashboards/tails never see (RCA 2026-05-01 dev 8687).
+    const sourceType = Array.isArray(p.entries)
+        ? 'inline-array'
+        : typeof p.entries === 'string'
+            ? 'inline-or-file'
+            : typeof p.source === 'string'
+                ? 'directory'
+                : 'none';
+    const inlineCount = Array.isArray(p.entries) ? p.entries.length : undefined;
+    (0, logger_1.logInfo)('[import] start', { mode, sourceType, inlineCount, source: typeof p.source === 'string' ? p.source : undefined });
     if (Array.isArray(p.entries)) {
         entries = p.entries;
     }
     else if (typeof p.entries === 'string') {
         const inlineEntries = parseInlineEntries(p.entries);
-        if (inlineEntries.error)
+        if (inlineEntries.error) {
+            warnStruct('[import] rejected', { reason: 'inline-parse-error', detail: inlineEntries.error });
             return inlineEntries.error;
+        }
         if (inlineEntries.entries) {
             entries = inlineEntries.entries;
         }
         else {
             const filePath = path_1.default.resolve(p.entries);
-            if (!isPathAllowed(filePath))
+            if (!isPathAllowed(filePath)) {
+                warnStruct('[import] rejected', { reason: 'path-not-allowed', path: filePath });
                 return { error: 'entries path is outside allowed directories', path: filePath };
-            if (!fs_1.default.existsSync(filePath))
+            }
+            if (!fs_1.default.existsSync(filePath)) {
+                warnStruct('[import] rejected', { reason: 'entries-file-not-found', path: filePath });
                 return { error: 'entries file not found', path: filePath };
+            }
             try {
                 const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
-                if (!Array.isArray(raw))
+                if (!Array.isArray(raw)) {
+                    warnStruct('[import] rejected', { reason: 'entries-file-not-array', path: filePath });
                     return { error: 'entries file must contain a JSON array', path: filePath };
+                }
                 entries = raw;
             }
             catch (e) {
+                warnStruct('[import] rejected', { reason: 'entries-file-parse-error', path: filePath, detail: e.message });
                 return { error: 'entries file parse error', path: filePath, detail: e.message };
             }
         }
     }
     else if (typeof p.source === 'string') {
         const dirPath = path_1.default.resolve(p.source);
-        if (!isPathAllowed(dirPath))
+        if (!isPathAllowed(dirPath)) {
+            warnStruct('[import] rejected', { reason: 'source-not-allowed', path: dirPath });
             return { error: 'source path is outside allowed directories', path: dirPath };
-        if (!fs_1.default.existsSync(dirPath))
+        }
+        if (!fs_1.default.existsSync(dirPath)) {
+            warnStruct('[import] rejected', { reason: 'source-not-found', path: dirPath });
             return { error: 'source directory not found', path: dirPath };
+        }
         let stat;
         try {
             stat = fs_1.default.statSync(dirPath);
         }
         catch (e) {
+            warnStruct('[import] rejected', { reason: 'source-inaccessible', path: dirPath, detail: e.message });
             return { error: 'source path inaccessible', path: dirPath, detail: e.message };
         }
-        if (!stat.isDirectory())
+        if (!stat.isDirectory()) {
+            warnStruct('[import] rejected', { reason: 'source-not-directory', path: dirPath });
             return { error: 'source path is not a directory', path: dirPath };
+        }
         const files = fs_1.default.readdirSync(dirPath).filter(f => f.endsWith('.json') && !f.startsWith('_'));
         entries = [];
         for (const fname of files) {
@@ -95,14 +130,18 @@ function parseInlineEntries(rawEntries) {
                 if (parsed && typeof parsed === 'object' && parsed.id)
                     entries.push(parsed);
             }
-            catch { /* skip unparseable files */ }
+            catch (e) {
+                warnStruct('[import] file skipped (parse error)', { file: fname, detail: e.message });
+            }
         }
     }
     else {
         entries = [];
     }
-    if (!entries.length)
+    if (!entries.length) {
+        warnStruct('[import] rejected', { reason: 'no-entries' });
         return { error: 'no entries' };
+    }
     const dir = (0, indexContext_1.getInstructionsDir)();
     if (!fs_1.default.existsSync(dir))
         fs_1.default.mkdirSync(dir, { recursive: true });
@@ -124,13 +163,16 @@ function parseInlineEntries(rawEntries) {
         ].filter((issue) => !!issue);
         const surfaceValidation = e ? (0, instructionRecordValidation_1.validateInstructionInputSurface)(e) : { validationErrors: [], hints: [], schemaRef: 'index_add#input' };
         if (!e || requiredFieldErrors.length || surfaceValidation.validationErrors.length) {
-            errors.push({ id, error: formatImportValidationError([...requiredFieldErrors, ...surfaceValidation.validationErrors]) });
+            const errMsg = formatImportValidationError([...requiredFieldErrors, ...surfaceValidation.validationErrors]);
+            errors.push({ id, error: errMsg });
+            warnStruct('[import] entry rejected', { id, reason: 'invalid-input', error: errMsg });
             continue;
         }
         const bodyTrimmed = typeof e.body === 'string' ? e.body.trim() : String(e.body);
         const { bodyWarnLength: importBodyMax } = (0, runtimeConfig_1.getRuntimeConfig)().index;
         if (bodyTrimmed.length > importBodyMax) {
             errors.push({ id: e.id, error: `body_too_large: ${bodyTrimmed.length} chars exceeds ${importBodyMax} limit. Split into cross-linked instructions.` });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'body-too-large', length: bodyTrimmed.length, limit: importBodyMax });
             continue;
         }
         const file = path_1.default.join(dir, `${e.id}.json`);
@@ -143,6 +185,7 @@ function parseInlineEntries(rawEntries) {
         if (!categories.length) {
             if (instructionsCfg.requireCategory) {
                 errors.push({ id: e.id, error: 'category_required' });
+                warnStruct('[import] entry rejected', { id: e.id, reason: 'category-required' });
                 continue;
             }
             categories = ['uncategorized'];
@@ -168,10 +211,12 @@ function parseInlineEntries(rawEntries) {
         }
         if (e.priorityTier === 'P1' && (!categories.length || !e.owner)) {
             errors.push({ id: e.id, error: 'P1 requires category & owner' });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'p1-requires-category-and-owner' });
             continue;
         }
         if ((e.requirement === 'mandatory' || e.requirement === 'critical') && !e.owner) {
             errors.push({ id: e.id, error: 'mandatory/critical require owner' });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'mandatory-critical-require-owner', requirement: e.requirement });
             continue;
         }
         if (fileExists && mode === 'skip') {
@@ -194,7 +239,9 @@ function parseInlineEntries(rawEntries) {
         }
         const recordValidation = (0, instructionRecordValidation_1.validateInstructionRecord)(record);
         if (recordValidation.validationErrors.length) {
-            errors.push({ id: e.id, error: formatImportValidationError(recordValidation.validationErrors) });
+            const errMsg = formatImportValidationError(recordValidation.validationErrors);
+            errors.push({ id: e.id, error: errMsg });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'record-validation-failed', error: errMsg });
             continue;
         }
         try {
@@ -202,10 +249,14 @@ function parseInlineEntries(rawEntries) {
         }
         catch (err) {
             if ((0, instructionRecordValidation_2.isInstructionValidationError)(err)) {
-                errors.push({ id: e.id, error: formatImportValidationError(err.validationErrors) });
+                const errMsg = formatImportValidationError(err.validationErrors);
+                errors.push({ id: e.id, error: errMsg });
+                (0, logger_1.logError)('[import] entry write rejected', { id: e.id, reason: 'validation-failed-at-write', error: errMsg });
                 continue;
             }
-            errors.push({ id: e.id, error: `write-failed: ${err.message || 'unknown'}` });
+            const writeMsg = err.message || 'unknown';
+            errors.push({ id: e.id, error: `write-failed: ${writeMsg}` });
+            (0, logger_1.logError)('[import] entry write failed', { id: e.id, error: writeMsg, stack: err.stack });
             continue;
         }
         if (fileExists && mode === 'overwrite')
@@ -229,10 +280,17 @@ function parseInlineEntries(rawEntries) {
     if (verificationErrors.length) {
         errors.push(...verificationErrors);
         (0, auditLog_1.logAudit)('import_verification', verificationErrors.map(v => v.id), { missingAfterReload: verificationErrors.length });
+        (0, logger_1.logError)('[import] verification failed', { missingAfterReload: verificationErrors.length, ids: verificationErrors.map(v => v.id) });
     }
     const verifiedCount = writtenIds.length - verificationErrors.length;
     const summary = { hash: st.hash, imported, skipped, overwritten, total: entries.length, errors, verified: verificationErrors.length === 0, verifiedCount, verificationErrorCount: verificationErrors.length };
     (0, auditLog_1.logAudit)('import', entries.map(e => e.id), { imported, skipped, overwritten, errors: errors.length, verified: verificationErrors.length === 0 });
+    if (errors.length) {
+        warnStruct('[import] complete with errors', { imported, skipped, overwritten, total: entries.length, errorCount: errors.length, verifiedCount, verificationErrorCount: verificationErrors.length, errorIds: errors.map(e => e.id) });
+    }
+    else {
+        (0, logger_1.logInfo)('[import] complete', { imported, skipped, overwritten, total: entries.length, verifiedCount });
+    }
     (0, manifestManager_1.attemptManifestUpdate)();
     return summary;
 }));