@ekkos/cli 1.4.2 → 1.5.0

package/dist/local/living-docs-manager.js

@@ -2,12 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalLivingDocsManager = void 0;
 const fs_1 = require("fs");
-const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const path_1 = require("path");
 const os_1 = require("os");
 const scan_js_1 = require("../commands/scan.js");
 const stack_detection_js_1 = require("./stack-detection.js");
+const git_utils_js_1 = require("./git-utils.js");
+const diff_engine_js_1 = require("./diff-engine.js");
+const entity_extractor_js_1 = require("./entity-extractor.js");
+const notifier_js_1 = require("../utils/notifier.js");
 const language_config_js_1 = require("./language-config.js");
 // ── Language-adaptive defaults (overridden per-system when stack is detected) ──
 const DEFAULT_EXCLUDED_DIRS = new Set([
@@ -231,12 +234,14 @@ function isWatchableFile(relativePath) {
         return false;
     if (name.startsWith('.'))
         return false;
-    if (name.endsWith('.log') || name.endsWith('.tmp') || name.endsWith('.swp'))
+    // Ignore .log, .tmp, .swp and the atomic write temp files (.ekkOS_CONTEXT.md.PID.TIME.tmp)
+    if (/\.(log|tmp|swp)$/i.test(name) || name.includes('.ekkOS_CONTEXT.md'))
         return false;
     return true;
 }
-function formatDate(date) {
-    return date.toISOString().slice(0, 10);
+function parseStoredFingerprint(markdown) {
+    const match = markdown.match(/^invalidation_fingerprint:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
 }
 function escapeInline(value) {
     return value.replace(/\r?\n/g, ' ').trim();
@@ -289,70 +294,6 @@ function extractEnvVars(contents) {
     }
     return [...vars].sort().slice(0, 20);
 }
-function readRecentGitChanges(repoRoot, directoryPath, timeZone) {
-    try {
-        const scope = directoryPath === '.' ? '.' : directoryPath;
-        // Use %s (subject) + --stat scoped to this directory for richer context.
-        // Format: epoch\tsubject\tfiles-changed summary
-        const output = (0, child_process_1.execSync)(`git -C ${JSON.stringify(repoRoot)} log --max-count=10 --pretty=format:"%ct%x09%s%x09%b" --stat -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 64 }).trim();
-        if (!output)
-            return [];
-        // Parse: format is "epoch\tsubject\tbody" followed by --stat lines per commit.
-        // Commits are separated by blank lines between stat block and next header.
-        const entries = [];
-        const blocks = output.split(/\n(?="\d+\t)/);
-        for (const block of blocks) {
-            const lines = block.split('\n');
-            const header = (lines[0] || '').replace(/^"|"$/g, '');
-            const parts = header.split('\t');
-            const epochSeconds = parts[0];
-            const subject = parts[1] || '';
-            // Body is the "why" — commit message body after the subject line
-            const body = (parts[2] || '').trim();
-            const epochMs = Number(epochSeconds || '0') * 1000;
-            if (!epochMs)
-                continue;
-            // Extract changed file names from stat lines (e.g. " src/commands/run.ts | 42 +++---")
-            const changedFiles = [];
-            for (let i = 1; i < lines.length; i++) {
-                const statMatch = lines[i].match(/^\s*(.+?)\s*\|\s*\d+/);
-                if (statMatch) {
-                    const filePath = statMatch[1].trim();
-                    if (scope === '.' || filePath.startsWith(scope + '/') || filePath.startsWith(scope.replace(/^\.\//, '') + '/')) {
-                        const shortName = filePath.split('/').pop() || filePath;
-                        changedFiles.push(shortName);
-                    }
-                }
-            }
-            const timestamp = formatZonedTimestamp(new Date(epochMs), timeZone);
-            // Build rich message: subject + files + body (why)
-            let message = subject || 'Updated local code';
-            if (changedFiles.length > 0) {
-                message += ` — files: ${changedFiles.slice(0, 5).join(', ')}${changedFiles.length > 5 ? ` +${changedFiles.length - 5} more` : ''}`;
-            }
-            // Include first line of body as the "why" if it exists and isn't just repeating the subject
-            if (body && !body.toLowerCase().startsWith(subject.toLowerCase().slice(0, 20))) {
-                const bodyFirstLine = body.split('\n')[0].slice(0, 120);
-                if (bodyFirstLine.length > 10) {
-                    message += ` | ${bodyFirstLine}`;
-                }
-            }
-            entries.push({
-                date: timestamp || formatDate(new Date()),
-                timestamp,
-                message,
-            });
-        }
-        return entries;
-    }
-    catch {
-        return [];
-    }
-}
-function parseStoredFingerprint(markdown) {
-    const match = markdown.match(/^invalidation_fingerprint:\s*(.+)$/m);
-    return match ? match[1].trim() : null;
-}
 function parseStoredTemplateVersion(markdown) {
     const match = markdown.match(/^compiler_template_version:\s*(.+)$/m);
     return match ? match[1].trim() : null;
@@ -385,35 +326,6 @@ function resolveUserTimeZone(preferred) {
     }
     return 'UTC';
 }
-function formatZonedTimestamp(value, timeZone) {
-    const date = value instanceof Date ? value : new Date(value);
-    if (Number.isNaN(date.getTime()))
-        return new Date().toISOString();
-    const parts = new Intl.DateTimeFormat('en-US', {
-        timeZone,
-        year: 'numeric',
-        month: '2-digit',
-        day: '2-digit',
-        hour: '2-digit',
-        minute: '2-digit',
-        second: '2-digit',
-        hourCycle: 'h23',
-    }).formatToParts(date);
-    const map = Object.fromEntries(parts
-        .filter(part => part.type !== 'literal')
-        .map(part => [part.type, part.value]));
-    const asUtc = Date.UTC(Number(map.year), Number(map.month) - 1, Number(map.day), Number(map.hour), Number(map.minute), Number(map.second), date.getUTCMilliseconds());
-    const offsetMinutes = Math.round((asUtc - date.getTime()) / 60000);
-    const zoned = new Date(date.getTime() + offsetMinutes * 60000);
-    const sign = offsetMinutes >= 0 ? '+' : '-';
-    const absOffset = Math.abs(offsetMinutes);
-    const pad = (num, width = 2) => num.toString().padStart(width, '0');
-    return [
-        `${pad(zoned.getUTCFullYear(), 4)}-${pad(zoned.getUTCMonth() + 1)}-${pad(zoned.getUTCDate())}`,
-        `T${pad(zoned.getUTCHours())}:${pad(zoned.getUTCMinutes())}:${pad(zoned.getUTCSeconds())}.${pad(zoned.getUTCMilliseconds(), 3)}`,
-        `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`,
-    ].join('');
-}
 class LocalLivingDocsManager {
     constructor(options) {
         this.scopePath = '.';
@@ -432,6 +344,7 @@ class LocalLivingDocsManager {
         this.timeZone = resolveUserTimeZone(options.timeZone);
         this.pollIntervalMs = options.pollIntervalMs ?? 5000;
         this.flushDebounceMs = options.flushDebounceMs ?? 2500;
+        this.richAnalysis = options.richAnalysis ?? true;
         this.onLog = options.onLog;
         this.repoRoot = this.targetPath;
         this.watchRoot = this.targetPath;
@@ -618,23 +531,35 @@ class LocalLivingDocsManager {
             return;
         const changedFiles = [...this.pendingFiles].sort();
         this.pendingFiles.clear();
+        this.log(`Processing ${changedFiles.length} changed files: ${changedFiles.join(', ')}`);
         let affectedSystems = this.findAffectedSystems(changedFiles);
         if (affectedSystems.length === 0) {
+            this.log('No systems affected by these files. Refreshing systems registry...');
             this.refreshSystems(true);
             affectedSystems = this.findAffectedSystems(changedFiles);
         }
         if (affectedSystems.length === 0) {
-            this.log(`No living-doc systems matched ${changedFiles.length} changed paths`);
+            this.log(`No living-doc systems matched ${changedFiles.length} changed paths: ${changedFiles.slice(0, 3).join(', ')}`);
             return;
         }
-        this.log(`Compiling ${affectedSystems.length} local system(s) from ${changedFiles.length} file change(s)`);
+        this.log(`Compiling ${affectedSystems.length} local system(s): ${affectedSystems.map(s => s.system_id).join(', ')}`);
         for (const system of affectedSystems) {
-            await this.compileSystem(system, `${changedFiles.length} local file change${changedFiles.length === 1 ? '' : 's'}`, changedFiles);
+            // Filter changed files to only those within this system. 
+            // Paths in changedFiles are already repo-relative.
+            const systemSpecificChanges = changedFiles.filter(f => matchesDirectoryPath(f, system.directory_path));
+            if (systemSpecificChanges.length > 0) {
+                this.log(`Triggering compile for ${system.system_id} with ${systemSpecificChanges.length} files`);
+                await this.compileSystem(system, `${systemSpecificChanges.length} local file change${systemSpecificChanges.length === 1 ? '' : 's'}`, systemSpecificChanges);
+            }
+            else {
+                this.log(`System ${system.system_id} matched but no files were within its directory (${system.directory_path})`);
+            }
         }
     }
     findAffectedSystems(files) {
         const matched = new Map();
         for (const file of files) {
+            // file is already repo-relative
             for (const system of this.systems) {
                 if (matchesDirectoryPath(file, system.directory_path)) {
                     matched.set(system.system_id, system);
@@ -683,20 +608,33 @@ class LocalLivingDocsManager {
                     continue;
                 const systemRoot = doc.directory_path === '.' ? this.repoRoot : (0, path_1.join)(this.repoRoot, doc.directory_path);
                 const contextPath = (0, path_1.join)(systemRoot, 'ekkOS_CONTEXT.md');
-                // Only overwrite if local doc is locally-compiled (or doesn't exist)
+                // Only overwrite if the server doc is meaningfully different from what's on disk.
                 if ((0, fs_1.existsSync)(contextPath)) {
                     try {
                         const existing = (0, fs_1.readFileSync)(contextPath, 'utf-8');
                         const isServerCompiled = existing.includes('compiled_by: ekkOS Server Compiler')
                             || existing.includes('compiler_model: gemini')
                             || (existing.includes('compiled_by:') && !existing.includes('compiled_by: ekkOS Local Compiler'));
-                        // If already server-compiled, check if the new one is newer
+                        // If already server-compiled, only overwrite with a strictly newer version
                         if (isServerCompiled) {
                             const existingDate = existing.match(/last_compiled_at:\s*(.+)/)?.[1]?.trim();
                             if (existingDate && new Date(existingDate) >= new Date(doc.compiled_at)) {
                                 continue; // Existing is same or newer
                             }
                         }
+                        // Content hash check: don't write if the body hasn't actually changed.
+                        // Strip frontmatter timestamps before comparing to avoid false positives.
+                        const stripVolatile = (s) => s
+                            .replace(/^last_compiled_at: .+$/m, '')
+                            .replace(/^compiled_timezone: .+$/m, '')
+                            .replace(/^recompile_reason: .+$/m, '')
+                            .replace(/^days_since_last_change: .+$/m, '')
+                            .replace(/^activity_status: .+$/m, '')
+                            .replace(/^content_hash: .+$/m, '')
+                            .trim();
+                        if (stripVolatile(existing) === stripVolatile(doc.compiled_body)) {
+                            continue; // Body is identical — skip to avoid noisy git diff
+                        }
                     }
                     catch { /* overwrite on error */ }
                 }
@@ -788,20 +726,33 @@ class LocalLivingDocsManager {
             try {
                 const existing = (0, fs_1.readFileSync)(contextPath, 'utf-8');
                 // NEVER overwrite a server-compiled (Gemini) doc with the local mechanical template.
-                // Server docs are richer — they include narrative architecture, data flow, gotchas, etc.
-                // Instead: metadata-only patch (update frontmatter, preserve body).
                 const isServerCompiled = existing.includes('compiled_by: ekkOS Server Compiler')
                     || existing.includes('compiler_model: gemini')
                     || (existing.includes('compiled_by:') && !existing.includes('compiled_by: ekkOS Local Compiler'));
                 if (isServerCompiled) {
-                    // Phase 3: Metadata-only patching — update frontmatter fields without touching body
-                    this.patchServerDocMetadata(contextPath, existing, system, reason);
+                    // Only patch metadata + trigger analysis when actual source files changed.
+                    // On startup with no changes, skip entirely to avoid noisy git diffs.
+                    if (changedFiles.length > 0) {
+                        this.patchServerDocMetadata(contextPath, existing, system, reason);
+                        if (this.richAnalysis && this.apiUrl && this.apiKey) {
+                            void this.injectSemanticAnalysis(system, changedFiles);
+                        }
+                    }
                     return;
                 }
-                // Same fingerprint + same template version = nothing changed → skip
+                // Same fingerprint + same template version = source content unchanged → skip recompile.
+                // Only trigger semantic analysis when the caller explicitly passed changed files.
                 if (parseStoredFingerprint(existing) === fingerprint &&
                     existing.includes('\ncompiled_timezone: ') &&
                     parseStoredTemplateVersion(existing) === LOCAL_CONTEXT_TEMPLATE_VERSION) {
+                    if (this.richAnalysis && this.apiUrl && this.apiKey && changedFiles.length > 0) {
+                        void this.injectSemanticAnalysis(system, changedFiles);
+                    }
+                    return;
+                }
+                // If no files actually changed (startup scan), don't rewrite the doc
+                // just because the template version or timezone field differs.
+                if (changedFiles.length === 0 && parseStoredFingerprint(existing) === fingerprint) {
                     return;
                 }
             }
@@ -824,7 +775,7 @@ class LocalLivingDocsManager {
         // Language-aware key files and entry points
         const stackKeyFiles = new Set((0, language_config_js_1.getKeyFilesForStack)(stack).map(f => f.toLowerCase()));
         const dependencies = extractDependencies((0, path_1.join)(systemRoot, 'package.json'));
-        const recentChanges = readRecentGitChanges(this.repoRoot, system.directory_path, this.timeZone);
+        const recentChanges = (0, git_utils_js_1.readRecentGitChanges)(this.repoRoot, system.directory_path, this.timeZone);
         const entryFileNames = ['index.ts', 'index.tsx', 'index.js', 'main.ts', 'server.ts', 'app.ts',
             'main.py', 'app.py', 'manage.py', '__main__.py', 'main.rs', 'lib.rs', 'main.go', 'config.ru',
             'Program.cs', 'lib/main.dart'];
@@ -835,7 +786,7 @@ class LocalLivingDocsManager {
         const directoryCount = new Set(files
             .map(file => normalizePath(file.relativePath).split('/').slice(0, -1).join('/'))
             .filter(Boolean)).size;
-        const now = formatZonedTimestamp(new Date(), this.timeZone);
+        const now = (0, git_utils_js_1.formatZonedTimestamp)(new Date(), this.timeZone);
         const observedTimes = changedFiles
             .map(file => {
             try {
@@ -848,10 +799,10 @@ class LocalLivingDocsManager {
             .filter(time => !Number.isNaN(time))
             .sort((a, b) => a - b);
         const evidenceStart = observedTimes.length > 0
-            ? formatZonedTimestamp(new Date(observedTimes[0]), this.timeZone)
+            ? (0, git_utils_js_1.formatZonedTimestamp)(new Date(observedTimes[0]), this.timeZone)
             : (recentChanges[recentChanges.length - 1]?.timestamp || now);
         const evidenceEnd = observedTimes.length > 0
-            ? formatZonedTimestamp(new Date(observedTimes[observedTimes.length - 1]), this.timeZone)
+            ? (0, git_utils_js_1.formatZonedTimestamp)(new Date(observedTimes[observedTimes.length - 1]), this.timeZone)
             : (recentChanges[0]?.timestamp || now);
         const topExtensions = [...extCounts.entries()]
             .sort((a, b) => b[1] - a[1])
@@ -859,17 +810,7 @@ class LocalLivingDocsManager {
             .map(([ext, count]) => `${ext.replace(/^\./, '') || 'none'} (${count})`)
             .join(', ');
         // ── Dead code / activity detection ──────────────────────────────────────
-        const lastCommitEpochMs = (() => {
-            try {
-                const scope = system.directory_path === '.' ? '.' : system.directory_path;
-                // Exclude ekkOS_CONTEXT.md from the query so auto-generated writes don't mask staleness
-                const raw = (0, child_process_1.execSync)(`git -C ${JSON.stringify(this.repoRoot)} log --max-count=1 --pretty=format:%ct -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-                return raw ? Number(raw) * 1000 : null;
-            }
-            catch {
-                return null;
-            }
-        })();
+        const lastCommitEpochMs = (0, git_utils_js_1.getLastCommitTimestamp)(this.repoRoot, system.directory_path);
         const daysSinceLastChange = lastCommitEpochMs
             ? Math.floor((Date.now() - lastCommitEpochMs) / (1000 * 60 * 60 * 24))
             : null;
@@ -1011,6 +952,121 @@ class LocalLivingDocsManager {
         (0, fs_1.writeFileSync)(tmpPath, markdown, 'utf-8');
         (0, fs_1.renameSync)(tmpPath, contextPath);
         this.log(`Wrote ${normalizePath((0, path_1.relative)(this.repoRoot, contextPath))}${stack.language !== 'unknown' ? ` [${stack.language}${stack.framework ? `/${stack.framework}` : ''}]` : ''}`);
+        // Phase 3: Trigger Server-Side Semantic Analysis if --rich is enabled
+        if (this.richAnalysis && this.apiUrl && this.apiKey && changedFiles.length > 0) {
+            this.log(`Triggering rich semantic analysis for ${system.system_id} based on ${changedFiles.length} file change(s)...`);
+            void this.injectSemanticAnalysis(system, changedFiles);
+        }
+    }
+    /**
+     * Calls the server-side semantic analyzer and injects rich insights into the context file.
+     */
+    async injectSemanticAnalysis(system, changedFiles) {
+        const systemRoot = system.directory_path === '.' ? this.repoRoot : (0, path_1.join)(this.repoRoot, system.directory_path);
+        const contextPath = (0, path_1.join)(systemRoot, 'ekkOS_CONTEXT.md');
+        try {
+            // 1. Extract diff and local entities
+            const { rawDiff } = await (0, diff_engine_js_1.getSemanticDiff)({
+                repoRoot: this.repoRoot,
+                directoryPath: system.directory_path
+            });
+            if (!rawDiff) {
+                this.log(`No semantic diff found for ${system.system_id}, skipping rich analysis.`);
+                return;
+            }
+            const entities = (0, entity_extractor_js_1.extractEntitiesFromDiff)(rawDiff);
+            // 2. POST to ekkOS cloud for rich analysis (Directive Audit + Cascade + Explanation)
+            this.log(`Requesting rich semantic analysis for ${system.system_id} from ekkOS Cloud (${this.apiUrl})...`);
+            const timeoutController = new AbortController();
+            const id = setTimeout(() => timeoutController.abort(), 20000); // 20s timeout
+            const res = await fetch(`${this.apiUrl}/api/v1/cortex/analyze-diff`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    diff: rawDiff,
+                    directory_path: system.directory_path,
+                    system_id: system.system_id,
+                    entities
+                }),
+                signal: timeoutController.signal,
+            });
+            clearTimeout(id);
+            if (!res.ok) {
+                const errorText = await res.text();
+                this.log(`Semantic analysis API failed (${res.status} ${res.statusText}): ${errorText.slice(0, 200)}`);
+                return;
+            }
+            const data = await res.json();
+            if (!data.success || !data.result.markdown) {
+                this.log(`Semantic analysis returned no results for ${system.system_id}`);
+                return;
+            }
+            // 2.5 Send desktop notification if requested
+            if (data.result.shouldNotify && data.result.notificationSummary) {
+                (0, notifier_js_1.sendDesktopNotification)({
+                    title: `ekkOS: ${system.system_id}`,
+                    message: data.result.notificationSummary,
+                    urgency: 'critical',
+                    systemId: system.system_id
+                });
+            }
+            // 3. Prepare the analysis block
+            let analysisMarkdown = data.result.markdown.trim();
+            // If we are injecting into a doc, and it's a server-compiled doc, 
+            // we should ensure the changed files are listed (since server body won't have them)
+            if (changedFiles.length > 0 && !analysisMarkdown.includes('These') && !analysisMarkdown.includes('file(s) changed')) {
+                const fileList = changedFiles.map(f => `- \`${f.split('/').pop()}\``).join('\n');
+                const fileHeader = `#### 📝 Recent Local Changes\nThese ${changedFiles.length} file(s) changed since last compile:\n\n${fileList}\n`;
+                analysisMarkdown = `${fileHeader}\n${analysisMarkdown}`;
+            }
+            // 4. Inject into the context file body
+            const existing = (0, fs_1.readFileSync)(contextPath, 'utf-8');
+            const activeWorkHeader = '## Active Work';
+            const systemInfoHeader = '## System Info';
+            const endMarker = '<!-- EKKOS_AUTOGENERATED_END -->';
+            let insertIndex = existing.indexOf(activeWorkHeader);
+            let limitIndex = -1;
+            if (insertIndex !== -1) {
+                // Section exists: append to it
+                const nextSectionIndex = existing.indexOf('\n## ', insertIndex + activeWorkHeader.length);
+                const endBlockIndex = existing.indexOf(endMarker, insertIndex);
+                limitIndex = nextSectionIndex !== -1 ? Math.min(nextSectionIndex, endBlockIndex) : endBlockIndex;
+            }
+            else {
+                // Section missing: try to insert before System Info or at the end of autogenerated block
+                const sysInfoIndex = existing.indexOf(systemInfoHeader);
+                if (sysInfoIndex !== -1) {
+                    insertIndex = sysInfoIndex;
+                    limitIndex = sysInfoIndex;
+                }
+                else {
+                    const endMarkerIndex = existing.indexOf(endMarker);
+                    if (endMarkerIndex !== -1) {
+                        insertIndex = endMarkerIndex;
+                        limitIndex = endMarkerIndex;
+                    }
+                }
+            }
+            if (insertIndex !== -1) {
+                const before = existing.slice(0, limitIndex);
+                const after = existing.slice(limitIndex);
+                // Clean up formatting: ensure sections are separated by double newlines
+                // If we inserted before System Info, we might need a header if it was missing
+                const headerPrefix = existing.includes(activeWorkHeader) ? '' : `## Active Work\n\n`;
+                const patched = `${before.trim()}\n\n${headerPrefix}${analysisMarkdown}\n\n${after.trim()}`;
+                (0, fs_1.writeFileSync)(contextPath, patched, 'utf-8');
+                this.log(`✅ Successfully injected rich semantic analysis into ${system.system_id}`);
+            }
+            else {
+                this.log(`Could not find a suitable insertion point in ${contextPath} to inject analysis.`);
+            }
+        }
+        catch (err) {
+            this.log(`Rich analysis failed: ${err.message}`);
+        }
     }
     /**
      * Metadata-only patch for server-compiled docs.
@@ -1019,16 +1075,7 @@ class LocalLivingDocsManager {
      */
     patchServerDocMetadata(contextPath, existing, system, reason) {
         try {
-            const lastCommitEpochMs = (() => {
-                try {
-                    const scope = system.directory_path === '.' ? '.' : system.directory_path;
-                    const raw = (0, child_process_1.execSync)(`git -C ${JSON.stringify(this.repoRoot)} log --max-count=1 --pretty=format:%ct -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-                    return raw ? Number(raw) * 1000 : null;
-                }
-                catch {
-                    return null;
-                }
-            })();
+            const lastCommitEpochMs = (0, git_utils_js_1.getLastCommitTimestamp)(this.repoRoot, system.directory_path);
             const daysSinceLastChange = lastCommitEpochMs
                 ? Math.floor((Date.now() - lastCommitEpochMs) / (1000 * 60 * 60 * 24))
                 : null;
@@ -1039,7 +1086,7 @@ class LocalLivingDocsManager {
                 else if (daysSinceLastChange >= 30)
                     activityStatus = 'stale';
             }
-            const now = formatZonedTimestamp(new Date(), this.timeZone);
+            const now = (0, git_utils_js_1.formatZonedTimestamp)(new Date(), this.timeZone);
             // Patch only approved fields in frontmatter, preserve body byte-for-byte
             const firstDash = existing.indexOf('---');
             const frontmatterEnd = existing.indexOf('---', firstDash + 3);
@@ -1070,12 +1117,6 @@ class LocalLivingDocsManager {
             }
             const result = patched + body;
             const finalResult = lineEnding === '\r\n' ? result.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n') : result;
-            // Skip write if the only change is last_compiled_at timestamp — prevents git noise
-            // Compare by stripping the timestamp lines from both old and new
-            const stripTimestamps = (s) => s.replace(/^last_compiled_at: .+$/m, '').replace(/^compiled_timezone: .+$/m, '');
-            if (stripTimestamps(existing) === stripTimestamps(finalResult)) {
-                return; // Nothing meaningful changed — don't touch the file
-            }
             // Atomic write
             const tmpPath = (0, path_1.join)((0, path_1.dirname)(contextPath), `.ekkOS_CONTEXT.md.${process.pid}.tmp`);
             (0, fs_1.writeFileSync)(tmpPath, finalResult, 'utf-8');

package/dist/utils/notifier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ekkOS Desktop Notifier
+ * Cross-platform desktop notifications for real-time architectural feedback.
+ */
+export type NotificationUrgency = 'low' | 'normal' | 'critical';
+export interface NotificationOptions {
+    title: string;
+    message: string;
+    urgency?: NotificationUrgency;
+    systemId?: string;
+}
+/**
+ * Sends a native desktop notification to the user.
+ */
+export declare function sendDesktopNotification(options: NotificationOptions): void;

package/dist/utils/notifier.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendDesktopNotification = sendDesktopNotification;
+const node_notifier_1 = __importDefault(require("node-notifier"));
+const path_1 = __importDefault(require("path"));
+// const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Fallback to commonjs __dirname for current build config
+const ASSETS_DIR = path_1.default.resolve(__dirname, '../../assets');
+// Simple anti-spam state
+const lastNotificationTime = new Map();
+const NOTIFICATION_COOLDOWN_MS = 60000; // 1 minute per system
+/**
+ * Sends a native desktop notification to the user.
+ */
+function sendDesktopNotification(options) {
+    const { title, message, urgency = 'normal', systemId = 'global' } = options;
+    // Anti-spam check
+    const now = Date.now();
+    const lastTime = lastNotificationTime.get(systemId) || 0;
+    if (now - lastTime < NOTIFICATION_COOLDOWN_MS && urgency !== 'critical') {
+        return;
+    }
+    try {
+        node_notifier_1.default.notify({
+            title: title,
+            message: message,
+            icon: path_1.default.join(ASSETS_DIR, 'ekkOS-icon.png'), // Fallback if icon doesn't exist
+            sound: urgency === 'critical',
+            wait: false,
+        });
+        lastNotificationTime.set(systemId, now);
+    }
+    catch (err) {
+        // Non-fatal fallback - just log it
+        console.warn(`[Notifier] Failed to send notification: ${err.message}`);
+    }
+}

package/dist/utils/paths.d.ts

@@ -82,6 +82,10 @@ export declare function getLegacyMetaPath(sessionId: string): string;
  * ~/.ekkos/cache/sessions/{sessionId}.stream.jsonl
  */
 export declare function getLegacyStreamLogPath(sessionId: string): string;
+/**
+ * Get the path to the daemon control port file
+ */
+export declare function getDaemonPortPath(): string;
 /**
  * Ensure a directory exists (mkdirp)
  */

package/dist/utils/paths.js

@@ -58,6 +58,7 @@ exports.getInstanceFilePath = getInstanceFilePath;
 exports.getLegacyTurnsPath = getLegacyTurnsPath;
 exports.getLegacyMetaPath = getLegacyMetaPath;
 exports.getLegacyStreamLogPath = getLegacyStreamLogPath;
+exports.getDaemonPortPath = getDaemonPortPath;
 exports.ensureDir = ensureDir;
 exports.ensureInstanceDir = ensureInstanceDir;
 exports.ensureBaseDirs = ensureBaseDirs;
@@ -189,6 +190,12 @@ function getLegacyMetaPath(sessionId) {
 function getLegacyStreamLogPath(sessionId) {
     return path.join(SESSIONS_DIR, `${sessionId}.stream.jsonl`);
 }
+/**
+ * Get the path to the daemon control port file
+ */
+function getDaemonPortPath() {
+    return path.join(EKKOS_DIR, 'synk', 'daemon.port');
+}
 /**
  * Ensure a directory exists (mkdirp)
  */

package/dist/utils/state.d.ts

@@ -15,6 +15,9 @@ export interface ClaudeSessionMetadata {
     geminiProjectId?: string;
     dashboardEnabled?: boolean;
     bypassEnabled?: boolean;
+    stdinPort?: number;
+    stdinToken?: string;
+    transcriptPath?: string;
 }
 export interface ActiveSession extends ClaudeSessionMetadata {
     sessionId: string;

package/dist/utils/stdin-relay.d.ts

@@ -0,0 +1,37 @@
+/**
+ * stdin-relay.ts — Universal Session Attach (Phase 1)
+ *
+ * Lightweight HTTP server bound to 127.0.0.1 that accepts remote input
+ * and injects it into the running PTY's stdin. The daemon (or any local
+ * process with the auth token) can POST text to be typed into Claude.
+ *
+ * Security:
+ *  - Binds to 127.0.0.1 only (no network exposure)
+ *  - Requires a one-time token generated at startup
+ *  - Token is stored in active-sessions.json (filesystem-permission scoped)
+ */
+export interface StdinRelayOptions {
+    /** Function to write data into the PTY stdin */
+    write: (data: string) => void;
+    /** Optional callback when a remote client attaches */
+    onAttach?: (remoteInfo: string) => void;
+    /** Optional debug logger */
+    dlog?: (...args: unknown[]) => void;
+}
+export interface StdinRelayHandle {
+    /** The localhost port the relay is listening on */
+    port: number;
+    /** The auth token required to send input */
+    token: string;
+    /** Stop the relay server */
+    stop: () => Promise<void>;
+}
+/**
+ * Start a stdin relay HTTP server on a random available port.
+ *
+ * Endpoints:
+ *   POST /stdin   — inject text into the PTY (body: { text: string })
+ *   GET  /health  — check if session is alive
+ *   GET  /status  — session metadata (attached clients, uptime)
+ */
+export declare function startStdinRelay(options: StdinRelayOptions): Promise<StdinRelayHandle>;