instar 0.7.45 → 0.7.46

package/.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

package/.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_evM5LcItYL3IAmw8zNvEPGrHeaya","orgId":"team_dHctwIDcV3X9ydapQlCPHFGI","projectName":"claude-agent-kit"}

package/dist/commands/server.js

@@ -9,6 +9,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import pc from 'picocolors';
 import { loadConfig, ensureStateDir, detectTmuxPath } from '../core/Config.js';
@@ -35,6 +36,24 @@ import { QuotaTracker } from '../monitoring/QuotaTracker.js';
 import { AccountSwitcher } from '../monitoring/AccountSwitcher.js';
 import { QuotaNotifier } from '../monitoring/QuotaNotifier.js';
 import { classifySessionDeath } from '../monitoring/QuotaExhaustionDetector.js';
+import { installAutoStart } from './setup.js';
+/**
+ * Check if autostart is installed for this project.
+ * Extracted from the CLI `autostart status` handler for programmatic use.
+ */
+function isAutostartInstalled(projectName) {
+    if (process.platform === 'darwin') {
+        const label = `ai.instar.${projectName}`;
+        const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+        return fs.existsSync(plistPath);
+    }
+    else if (process.platform === 'linux') {
+        const serviceName = `instar-${projectName}.service`;
+        const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', serviceName);
+        return fs.existsSync(servicePath);
+    }
+    return false;
+}
 /**
  * Respawn a session for a topic, including thread history in the bootstrap.
  * This prevents "thread drift" where respawned sessions lose context.
@@ -710,6 +729,77 @@ export async function startServer(options) {
             ...(config.evolution || {}),
         });
         console.log(pc.green('  Evolution system enabled'));
+        // Start MemoryPressureMonitor (platform-aware memory tracking)
+        const { MemoryPressureMonitor } = await import('../monitoring/MemoryPressureMonitor.js');
+        const memoryMonitor = new MemoryPressureMonitor({});
+        memoryMonitor.on('stateChange', ({ from, to, state: memState }) => {
+            // Gate scheduler spawning on memory pressure
+            if (scheduler && (to === 'elevated' || to === 'critical')) {
+                console.log(`[MemoryPressure] ${from} -> ${to} — scheduler should respect canSpawnSession()`);
+            }
+            // Alert via Telegram attention topic
+            if (telegram && to !== 'normal') {
+                const attentionTopicId = state.get('agent-attention-topic');
+                if (attentionTopicId) {
+                    telegram.sendToTopic(attentionTopicId, `Memory ${to}: ${memState.pressurePercent.toFixed(1)}% used, ${memState.freeGB.toFixed(1)}GB free (trend: ${memState.trend})`).catch(() => { });
+                }
+            }
+        });
+        memoryMonitor.start();
+        // Wire memory gate into scheduler
+        if (scheduler) {
+            const originalCanRun = scheduler.canRunJob;
+            scheduler.canRunJob = (priority) => {
+                // Check memory first
+                const memCheck = memoryMonitor.canSpawnSession();
+                if (!memCheck.allowed) {
+                    return false;
+                }
+                // Then check original gate (quota, etc.)
+                return originalCanRun(priority);
+            };
+        }
+        // Start CaffeinateManager (prevents macOS system sleep)
+        const { CaffeinateManager } = await import('../core/CaffeinateManager.js');
+        const caffeinateManager = new CaffeinateManager({ stateDir: config.stateDir });
+        caffeinateManager.start();
+        // Start SleepWakeDetector (re-validate sessions on wake)
+        const { SleepWakeDetector } = await import('../core/SleepWakeDetector.js');
+        const sleepWakeDetector = new SleepWakeDetector();
+        sleepWakeDetector.on('wake', async (event) => {
+            console.log(`[SleepWake] Wake detected after ~${event.sleepDurationSeconds}s sleep`);
+            // Re-validate tmux sessions
+            try {
+                const tmuxPath = detectTmuxPath();
+                if (tmuxPath) {
+                    const { execFileSync } = await import('child_process');
+                    const result = execFileSync(tmuxPath, ['list-sessions'], { encoding: 'utf-8', timeout: 5000 }).trim();
+                    console.log(`[SleepWake] tmux sessions after wake: ${result.split('\n').length}`);
+                }
+            }
+            catch {
+                console.warn('[SleepWake] tmux check failed after wake');
+            }
+            // Restart tunnel if configured
+            if (tunnel) {
+                try {
+                    await tunnel.stop();
+                    const tunnelUrl = await tunnel.start();
+                    console.log(`[SleepWake] Tunnel restarted: ${tunnelUrl}`);
+                }
+                catch (err) {
+                    console.error(`[SleepWake] Tunnel restart failed:`, err);
+                }
+            }
+            // Notify via Telegram attention topic
+            if (telegram) {
+                const attentionTopicId = state.get('agent-attention-topic');
+                if (attentionTopicId) {
+                    telegram.sendToTopic(attentionTopicId, `Wake detected after ~${event.sleepDurationSeconds}s sleep. Sessions re-validated.`).catch(() => { });
+                }
+            }
+        });
+        sleepWakeDetector.start();
         const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, publisher, viewer, tunnel, evolution });
         await server.start();
         // Start tunnel AFTER server is listening
@@ -723,9 +813,33 @@ export async function startServer(options) {
                 console.log(pc.yellow(`  Server running locally without tunnel. Fix tunnel config and restart.`));
             }
         }
+        // Self-healing: ensure autostart is installed so the server always restarts
+        // This is a non-negotiable requirement — the user must always be able to reach their agent remotely.
+        // If autostart isn't installed, install it silently. The agent should never require human intervention
+        // to ensure its own resilience.
+        try {
+            const hasTelegram = !!telegram;
+            const autostartInstalled = isAutostartInstalled(config.projectName);
+            if (!autostartInstalled) {
+                const installed = installAutoStart(config.projectName, config.projectDir, hasTelegram);
+                if (installed) {
+                    console.log(pc.green(`  Auto-start self-healed: installed ${process.platform === 'darwin' ? 'LaunchAgent' : 'systemd service'}`));
+                }
+                else {
+                    console.log(pc.yellow(`  Auto-start not available on ${process.platform}`));
+                }
+            }
+        }
+        catch (err) {
+            // Non-critical — don't crash the server over autostart
+            console.error(`  Auto-start check failed: ${err instanceof Error ? err.message : err}`);
+        }
         // Graceful shutdown
         const shutdown = async () => {
             console.log('\nShutting down...');
+            memoryMonitor.stop();
+            caffeinateManager.stop();
+            sleepWakeDetector.stop();
             autoUpdater.stop();
             autoDispatcher?.stop();
             if (tunnel)

package/dist/commands/setup.js

@@ -813,10 +813,7 @@ ${argsXml}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-        <key>SuccessfulExit</key>
-        <false/>
-    </dict>
+    <true/>
     <key>StandardOutPath</key>
     <string>${escapeXml(path.join(logDir, `${command}-launchd.log`))}</string>
     <key>StandardErrorPath</key>

package/dist/core/CaffeinateManager.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CaffeinateManager - Prevent macOS system sleep for Instar server lifetime.
+ *
+ * Maintains a `caffeinate -s` child process that prevents system sleep.
+ * A watchdog verifies it's alive every 30s and restarts if dead.
+ * PID is written to <stateDir>/caffeinate.pid for crash recovery.
+ *
+ * Only activates on macOS (process.platform === 'darwin').
+ * Uses EventEmitter pattern consistent with Instar conventions.
+ */
+import { EventEmitter } from 'node:events';
+export interface CaffeinateManagerConfig {
+    /** State directory for PID file storage */
+    stateDir: string;
+}
+export interface CaffeinateStatus {
+    running: boolean;
+    pid: number | null;
+    startedAt: string | null;
+    restartCount: number;
+    lastWatchdogCheck: string;
+}
+export declare class CaffeinateManager extends EventEmitter {
+    private process;
+    private watchdogInterval;
+    private pid;
+    private startedAt;
+    private restartCount;
+    private lastWatchdogCheck;
+    private stopping;
+    private pidFile;
+    constructor(config: CaffeinateManagerConfig);
+    /**
+     * Start caffeinate and the watchdog.
+     * Only activates on macOS.
+     */
+    start(): void;
+    /**
+     * Stop caffeinate and the watchdog cleanly.
+     */
+    stop(): void;
+    getStatus(): CaffeinateStatus;
+    private spawnCaffeinate;
+    private killCaffeinate;
+    private watchdog;
+    private cleanupStale;
+    private writePidFile;
+    private removePidFile;
+}
+//# sourceMappingURL=CaffeinateManager.d.ts.map

package/dist/core/CaffeinateManager.js

@@ -0,0 +1,180 @@
+/**
+ * CaffeinateManager - Prevent macOS system sleep for Instar server lifetime.
+ *
+ * Maintains a `caffeinate -s` child process that prevents system sleep.
+ * A watchdog verifies it's alive every 30s and restarts if dead.
+ * PID is written to <stateDir>/caffeinate.pid for crash recovery.
+ *
+ * Only activates on macOS (process.platform === 'darwin').
+ * Uses EventEmitter pattern consistent with Instar conventions.
+ */
+import { EventEmitter } from 'node:events';
+import { spawn, execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+const WATCHDOG_INTERVAL_MS = 30_000; // 30 seconds
+export class CaffeinateManager extends EventEmitter {
+    process = null;
+    watchdogInterval = null;
+    pid = null;
+    startedAt = null;
+    restartCount = 0;
+    lastWatchdogCheck = new Date().toISOString();
+    stopping = false;
+    pidFile;
+    constructor(config) {
+        super();
+        this.pidFile = path.join(config.stateDir, 'caffeinate.pid');
+    }
+    /**
+     * Start caffeinate and the watchdog.
+     * Only activates on macOS.
+     */
+    start() {
+        if (this.watchdogInterval)
+            return;
+        if (process.platform !== 'darwin') {
+            console.log('[CaffeinateManager] Not macOS — skipping sleep prevention');
+            return;
+        }
+        this.stopping = false;
+        this.cleanupStale();
+        this.spawnCaffeinate();
+        this.watchdogInterval = setInterval(() => this.watchdog(), WATCHDOG_INTERVAL_MS);
+        this.watchdogInterval.unref(); // Don't prevent process exit
+        console.log(`[CaffeinateManager] Started (watchdog: ${WATCHDOG_INTERVAL_MS / 1000}s)`);
+    }
+    /**
+     * Stop caffeinate and the watchdog cleanly.
+     */
+    stop() {
+        this.stopping = true;
+        if (this.watchdogInterval) {
+            clearInterval(this.watchdogInterval);
+            this.watchdogInterval = null;
+        }
+        this.killCaffeinate();
+        this.removePidFile();
+        console.log('[CaffeinateManager] Stopped');
+    }
+    getStatus() {
+        return {
+            running: this.process !== null && this.pid !== null,
+            pid: this.pid,
+            startedAt: this.startedAt,
+            restartCount: this.restartCount,
+            lastWatchdogCheck: this.lastWatchdogCheck,
+        };
+    }
+    spawnCaffeinate() {
+        try {
+            const proc = spawn('caffeinate', ['-s'], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            proc.unref();
+            this.process = proc;
+            this.pid = proc.pid ?? null;
+            this.startedAt = new Date().toISOString();
+            this.writePidFile();
+            proc.on('exit', (code, signal) => {
+                if (!this.stopping) {
+                    console.warn(`[CaffeinateManager] caffeinate exited (code: ${code}, signal: ${signal})`);
+                    this.emit('died', { code, signal });
+                }
+                this.process = null;
+                this.pid = null;
+            });
+            proc.on('error', (err) => {
+                console.error('[CaffeinateManager] caffeinate spawn error:', err.message);
+                this.process = null;
+                this.pid = null;
+            });
+            console.log(`[CaffeinateManager] caffeinate spawned (PID: ${this.pid})`);
+            this.emit('started', { pid: this.pid });
+        }
+        catch (err) {
+            console.error('[CaffeinateManager] Failed to spawn caffeinate:', err);
+        }
+    }
+    killCaffeinate() {
+        if (this.pid) {
+            try {
+                process.kill(this.pid, 'SIGTERM');
+            }
+            catch {
+                // Already dead
+            }
+        }
+        this.process = null;
+        this.pid = null;
+    }
+    watchdog() {
+        this.lastWatchdogCheck = new Date().toISOString();
+        if (this.stopping)
+            return;
+        if (this.pid) {
+            try {
+                process.kill(this.pid, 0);
+                return; // Still alive
+            }
+            catch {
+                console.warn(`[CaffeinateManager] caffeinate PID ${this.pid} is dead`);
+                this.process = null;
+                this.pid = null;
+            }
+        }
+        this.restartCount++;
+        console.log(`[CaffeinateManager] Restarting caffeinate (restart #${this.restartCount})`);
+        this.spawnCaffeinate();
+        this.emit('restarted', { restartCount: this.restartCount });
+    }
+    cleanupStale() {
+        try {
+            if (fs.existsSync(this.pidFile)) {
+                const stalePid = parseInt(fs.readFileSync(this.pidFile, 'utf-8').trim(), 10);
+                if (!isNaN(stalePid) && stalePid > 0) {
+                    try {
+                        const cmdline = execSync(`ps -p ${stalePid} -o comm= 2>/dev/null`, {
+                            encoding: 'utf-8',
+                            timeout: 3000,
+                        }).trim();
+                        if (cmdline.includes('caffeinate')) {
+                            process.kill(stalePid, 'SIGTERM');
+                            console.log(`[CaffeinateManager] Killed stale caffeinate (PID: ${stalePid})`);
+                        }
+                    }
+                    catch {
+                        // Process doesn't exist
+                    }
+                }
+                this.removePidFile();
+            }
+        }
+        catch {
+            // PID file doesn't exist or can't be read
+        }
+    }
+    writePidFile() {
+        if (!this.pid)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.pidFile), { recursive: true });
+            fs.writeFileSync(this.pidFile, String(this.pid));
+        }
+        catch (err) {
+            console.error('[CaffeinateManager] Failed to write PID file:', err);
+        }
+    }
+    removePidFile() {
+        try {
+            if (fs.existsSync(this.pidFile)) {
+                fs.unlinkSync(this.pidFile);
+            }
+        }
+        catch {
+            // Not critical
+        }
+    }
+}
+//# sourceMappingURL=CaffeinateManager.js.map

package/dist/lifeline/ServerSupervisor.js

@@ -97,7 +97,7 @@ export class ServerSupervisor extends EventEmitter {
             return false;
         try {
             // Get the instar CLI path
-            const cliPath = new URL('../../cli.js', import.meta.url).pathname;
+            const cliPath = new URL('../cli.js', import.meta.url).pathname;
             // --no-telegram: lifeline owns the Telegram connection, server should not poll
             const nodeCmd = ['node', cliPath, 'server', 'start', '--foreground', '--no-telegram']
                 .map(arg => `'${arg.replace(/'/g, "'\\''")}'`)

package/dist/lifeline/TelegramLifeline.d.ts

@@ -45,6 +45,10 @@ export declare class TelegramLifeline {
     private handleLifelineCommand;
     private replayQueue;
     private notifyServerDown;
+    /**
+     * Check if OS-level autostart is installed for this project.
+     */
+    private isAutostartInstalled;
     /**
      * Ensure the Lifeline topic exists. Recreates if deleted.
      */

package/dist/lifeline/TelegramLifeline.js

@@ -19,10 +19,12 @@
  * the full server crashes, runs out of memory, or gets stuck.
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import pc from 'picocolors';
 import { loadConfig, ensureStateDir } from '../core/Config.js';
 import { registerPort, unregisterPort, startHeartbeat } from '../core/PortRegistry.js';
+import { installAutoStart } from '../commands/setup.js';
 import { MessageQueue } from './MessageQueue.js';
 import { ServerSupervisor } from './ServerSupervisor.js';
 /**
@@ -127,7 +129,7 @@ export class TelegramLifeline {
         // Acquire exclusive lock — prevent multiple lifeline instances
         if (!acquireLockFile(this.lockPath)) {
             console.error(pc.red('[Lifeline] Another lifeline instance is already running. Exiting.'));
-            process.exit(0); // Clean exit — launchd won't respawn on clean exit with KeepAlive config
+            process.exit(0); // Clean exit — launchd will restart after ThrottleInterval, acting as a watchdog
         }
         // Register in port registry (lifeline owns the port claim)
         try {
@@ -166,6 +168,19 @@ export class TelegramLifeline {
                 setTimeout(() => this.replayQueue(), 5000); // Wait for server to fully start
             }
         }
+        // Self-healing: ensure autostart is installed so the lifeline persists across reboots.
+        // The user must always be able to reach their agent remotely — this is non-negotiable.
+        try {
+            if (!this.isAutostartInstalled()) {
+                const installed = installAutoStart(this.projectConfig.projectName, this.projectConfig.projectDir, true);
+                if (installed) {
+                    console.log(pc.green(`  Auto-start self-healed: installed ${process.platform === 'darwin' ? 'LaunchAgent' : 'systemd service'}`));
+                }
+            }
+        }
+        catch {
+            // Non-critical — don't crash the lifeline over autostart
+        }
         // Graceful shutdown
         const shutdown = async () => {
             console.log('\nLifeline shutting down...');
@@ -366,6 +381,22 @@ export class TelegramLifeline {
         await this.sendToTopic(topicId, `Server went down: ${reason}\n\nYour messages will be queued until recovery. Use /lifeline status to check.`).catch(() => { });
     }
     // ── Lifeline Topic ──────────────────────────────────────────
+    /**
+     * Check if OS-level autostart is installed for this project.
+     */
+    isAutostartInstalled() {
+        if (process.platform === 'darwin') {
+            const label = `ai.instar.${this.projectConfig.projectName}`;
+            const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+            return fs.existsSync(plistPath);
+        }
+        else if (process.platform === 'linux') {
+            const serviceName = `instar-${this.projectConfig.projectName}.service`;
+            const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', serviceName);
+            return fs.existsSync(servicePath);
+        }
+        return false;
+    }
     /**
      * Ensure the Lifeline topic exists. Recreates if deleted.
      */

package/dist/monitoring/HealthChecker.d.ts

@@ -33,6 +33,7 @@ export declare class HealthChecker {
     private checkTmux;
     private checkSessions;
     private checkScheduler;
+    private checkMemory;
     private checkStateDir;
 }
 //# sourceMappingURL=HealthChecker.d.ts.map

package/dist/monitoring/HealthChecker.js

@@ -26,6 +26,7 @@ export class HealthChecker {
         components.tmux = this.checkTmux();
         components.sessions = this.checkSessions();
         components.stateDir = this.checkStateDir();
+        components.memory = this.checkMemory();
         if (this.scheduler) {
             components.scheduler = this.checkScheduler();
         }
@@ -135,6 +136,27 @@ export class HealthChecker {
             lastCheck: now,
         };
     }
+    checkMemory() {
+        const now = new Date().toISOString();
+        try {
+            const os = require('node:os');
+            const totalBytes = os.totalmem();
+            const freeBytes = os.freemem();
+            const totalGB = totalBytes / (1024 ** 3);
+            const freeGB = freeBytes / (1024 ** 3);
+            const usedPercent = ((totalBytes - freeBytes) / totalBytes) * 100;
+            if (usedPercent >= 90) {
+                return { status: 'unhealthy', message: `Memory critical: ${usedPercent.toFixed(0)}% used (${freeGB.toFixed(1)}GB free)`, lastCheck: now };
+            }
+            if (usedPercent >= 75) {
+                return { status: 'degraded', message: `Memory elevated: ${usedPercent.toFixed(0)}% used (${freeGB.toFixed(1)}GB free)`, lastCheck: now };
+            }
+            return { status: 'healthy', message: `${usedPercent.toFixed(0)}% used (${freeGB.toFixed(1)}GB free / ${totalGB.toFixed(0)}GB total)`, lastCheck: now };
+        }
+        catch (err) {
+            return { status: 'degraded', message: `Memory check failed: ${err instanceof Error ? err.message : String(err)}`, lastCheck: now };
+        }
+    }
     checkStateDir() {
         const now = new Date().toISOString();
         try {

package/dist/monitoring/MemoryPressureMonitor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * MemoryPressureMonitor - Detect and respond to system memory pressure.
+ *
+ * Platform-aware: uses macOS `vm_stat` or Linux `/proc/meminfo`.
+ * EventEmitter pattern consistent with Instar conventions.
+ *
+ * Thresholds:
+ *   - normal   (< 60%): all operations allowed
+ *   - warning  (60-75%): log trend, notify
+ *   - elevated (75-90%): restrict session spawning
+ *   - critical (90%+): block all spawns, alert
+ *
+ * Includes trend tracking via ring buffer + linear regression.
+ */
+import { EventEmitter } from 'node:events';
+export type MemoryPressureState = 'normal' | 'warning' | 'elevated' | 'critical';
+export type MemoryTrend = 'rising' | 'stable' | 'falling';
+export interface MemoryState {
+    pressurePercent: number;
+    freeGB: number;
+    totalGB: number;
+    state: MemoryPressureState;
+    trend: MemoryTrend;
+    ratePerMin: number;
+    lastChecked: string;
+    stateChangedAt: string;
+    platform: string;
+}
+export interface MemoryPressureMonitorConfig {
+    /** Thresholds (percent). Defaults: warning=60, elevated=75, critical=90 */
+    thresholds?: {
+        warning?: number;
+        elevated?: number;
+        critical?: number;
+    };
+    /** Base check interval in ms. Default: 30000 */
+    checkIntervalMs?: number;
+}
+export declare class MemoryPressureMonitor extends EventEmitter {
+    private timeout;
+    private currentState;
+    private stateChangedAt;
+    private lastChecked;
+    private lastPressurePercent;
+    private lastFreeGB;
+    private lastTotalGB;
+    private ringBuffer;
+    private currentTrend;
+    private currentRatePerMin;
+    private thresholds;
+    private baseIntervalMs;
+    constructor(config?: MemoryPressureMonitorConfig);
+    start(): void;
+    stop(): void;
+    getState(): MemoryState;
+    /**
+     * Can a new session be spawned?
+     */
+    canSpawnSession(): {
+        allowed: boolean;
+        reason?: string;
+    };
+    private scheduleNext;
+    private check;
+    private classifyState;
+    /**
+     * Read system memory — platform-aware.
+     */
+    private readSystemMemory;
+    /**
+     * macOS: parse vm_stat
+     */
+    private parseVmStat;
+    /**
+     * Linux: parse /proc/meminfo
+     */
+    private parseProcMeminfo;
+    /**
+     * Linear regression over recent readings.
+     */
+    private detectTrend;
+}
+//# sourceMappingURL=MemoryPressureMonitor.d.ts.map

package/dist/monitoring/MemoryPressureMonitor.js

@@ -0,0 +1,242 @@
+/**
+ * MemoryPressureMonitor - Detect and respond to system memory pressure.
+ *
+ * Platform-aware: uses macOS `vm_stat` or Linux `/proc/meminfo`.
+ * EventEmitter pattern consistent with Instar conventions.
+ *
+ * Thresholds:
+ *   - normal   (< 60%): all operations allowed
+ *   - warning  (60-75%): log trend, notify
+ *   - elevated (75-90%): restrict session spawning
+ *   - critical (90%+): block all spawns, alert
+ *
+ * Includes trend tracking via ring buffer + linear regression.
+ */
+import { EventEmitter } from 'node:events';
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+const DEFAULT_THRESHOLDS = {
+    warning: 60,
+    elevated: 75,
+    critical: 90,
+};
+const RING_BUFFER_SIZE = 20;
+const TREND_WINDOW = 6;
+const PAGE_SIZE_BYTES = 16384; // macOS Apple Silicon
+// Adaptive intervals
+const INTERVALS = {
+    normal: 30_000,
+    warning: 15_000,
+    elevated: 10_000,
+    critical: 5_000,
+};
+export class MemoryPressureMonitor extends EventEmitter {
+    timeout = null;
+    currentState = 'normal';
+    stateChangedAt = new Date().toISOString();
+    lastChecked = new Date().toISOString();
+    lastPressurePercent = 0;
+    lastFreeGB = 0;
+    lastTotalGB = 0;
+    ringBuffer = [];
+    currentTrend = 'stable';
+    currentRatePerMin = 0;
+    thresholds;
+    baseIntervalMs;
+    constructor(config = {}) {
+        super();
+        this.thresholds = {
+            ...DEFAULT_THRESHOLDS,
+            ...config.thresholds,
+        };
+        this.baseIntervalMs = config.checkIntervalMs ?? 30_000;
+    }
+    start() {
+        if (this.timeout)
+            return;
+        this.check();
+        this.scheduleNext();
+        console.log(`[MemoryPressureMonitor] Started (platform: ${process.platform}, thresholds: ${JSON.stringify(this.thresholds)})`);
+    }
+    stop() {
+        if (this.timeout) {
+            clearTimeout(this.timeout);
+            this.timeout = null;
+        }
+    }
+    getState() {
+        return {
+            pressurePercent: this.lastPressurePercent,
+            freeGB: this.lastFreeGB,
+            totalGB: this.lastTotalGB,
+            state: this.currentState,
+            trend: this.currentTrend,
+            ratePerMin: this.currentRatePerMin,
+            lastChecked: this.lastChecked,
+            stateChangedAt: this.stateChangedAt,
+            platform: process.platform,
+        };
+    }
+    /**
+     * Can a new session be spawned?
+     */
+    canSpawnSession() {
+        switch (this.currentState) {
+            case 'normal':
+            case 'warning':
+                return { allowed: true };
+            case 'elevated':
+                return {
+                    allowed: false,
+                    reason: `Memory pressure elevated (${this.lastPressurePercent.toFixed(1)}%) — session spawn blocked`,
+                };
+            case 'critical':
+                return {
+                    allowed: false,
+                    reason: `Memory pressure critical (${this.lastPressurePercent.toFixed(1)}%) — all spawns blocked`,
+                };
+        }
+    }
+    scheduleNext() {
+        const intervalMs = INTERVALS[this.currentState] || this.baseIntervalMs;
+        this.timeout = setTimeout(() => {
+            this.check();
+            this.scheduleNext();
+        }, intervalMs);
+        this.timeout.unref(); // Don't prevent process exit
+    }
+    check() {
+        try {
+            const { pressurePercent, freeGB, totalGB } = this.readSystemMemory();
+            this.lastPressurePercent = pressurePercent;
+            this.lastFreeGB = freeGB;
+            this.lastTotalGB = totalGB;
+            this.lastChecked = new Date().toISOString();
+            // Ring buffer
+            this.ringBuffer.push({ timestamp: Date.now(), pressurePercent });
+            if (this.ringBuffer.length > RING_BUFFER_SIZE) {
+                this.ringBuffer.shift();
+            }
+            // Trend
+            const { trend, ratePerMin } = this.detectTrend();
+            this.currentTrend = trend;
+            this.currentRatePerMin = ratePerMin;
+            const newState = this.classifyState(pressurePercent);
+            if (newState !== this.currentState) {
+                const from = this.currentState;
+                this.currentState = newState;
+                this.stateChangedAt = new Date().toISOString();
+                console.log(`[MemoryPressureMonitor] ${from} -> ${newState} (${pressurePercent.toFixed(1)}%, ${freeGB.toFixed(1)}GB free, trend: ${trend})`);
+                this.emit('stateChange', { from, to: newState, state: this.getState() });
+            }
+        }
+        catch (error) {
+            console.error('[MemoryPressureMonitor] Check failed:', error);
+        }
+    }
+    classifyState(pressurePercent) {
+        if (pressurePercent >= this.thresholds.critical)
+            return 'critical';
+        if (pressurePercent >= this.thresholds.elevated)
+            return 'elevated';
+        if (pressurePercent >= this.thresholds.warning)
+            return 'warning';
+        return 'normal';
+    }
+    /**
+     * Read system memory — platform-aware.
+     */
+    readSystemMemory() {
+        if (process.platform === 'darwin') {
+            return this.parseVmStat();
+        }
+        else if (process.platform === 'linux') {
+            return this.parseProcMeminfo();
+        }
+        else {
+            // Fallback: use Node's process.memoryUsage (very rough)
+            const mem = process.memoryUsage();
+            const totalGB = require('os').totalmem() / (1024 ** 3);
+            const usedGB = mem.rss / (1024 ** 3);
+            return {
+                pressurePercent: (usedGB / totalGB) * 100,
+                freeGB: totalGB - usedGB,
+                totalGB,
+            };
+        }
+    }
+    /**
+     * macOS: parse vm_stat
+     */
+    parseVmStat() {
+        const output = execSync('vm_stat', { encoding: 'utf-8', timeout: 5000 });
+        const pageSizeMatch = output.match(/page size of (\d+) bytes/);
+        const pageSize = pageSizeMatch ? parseInt(pageSizeMatch[1], 10) : PAGE_SIZE_BYTES;
+        const parsePages = (label) => {
+            const match = output.match(new RegExp(`${label}:\\s+(\\d+)`));
+            return match ? parseInt(match[1], 10) : 0;
+        };
+        const freePages = parsePages('Pages free');
+        const activePages = parsePages('Pages active');
+        const inactivePages = parsePages('Pages inactive');
+        const wiredPages = parsePages('Pages wired down');
+        const compressorPages = parsePages('Pages occupied by compressor');
+        const purgeablePages = parsePages('Pages purgeable');
+        const totalPages = freePages + activePages + inactivePages + wiredPages + compressorPages;
+        const totalBytes = totalPages * pageSize;
+        const totalGB = totalBytes / (1024 ** 3);
+        const availablePages = freePages + inactivePages + purgeablePages;
+        const availableBytes = availablePages * pageSize;
+        const freeGB = availableBytes / (1024 ** 3);
+        const usedPages = totalPages - availablePages;
+        const pressurePercent = totalPages > 0 ? (usedPages / totalPages) * 100 : 0;
+        return { pressurePercent, freeGB, totalGB };
+    }
+    /**
+     * Linux: parse /proc/meminfo
+     */
+    parseProcMeminfo() {
+        const content = fs.readFileSync('/proc/meminfo', 'utf-8');
+        const parseKB = (key) => {
+            const match = content.match(new RegExp(`${key}:\\s+(\\d+)`));
+            return match ? parseInt(match[1], 10) : 0;
+        };
+        const totalKB = parseKB('MemTotal');
+        const availableKB = parseKB('MemAvailable') || (parseKB('MemFree') + parseKB('Buffers') + parseKB('Cached'));
+        const totalGB = totalKB / (1024 * 1024);
+        const freeGB = availableKB / (1024 * 1024);
+        const pressurePercent = totalKB > 0 ? ((totalKB - availableKB) / totalKB) * 100 : 0;
+        return { pressurePercent, freeGB, totalGB };
+    }
+    /**
+     * Linear regression over recent readings.
+     */
+    detectTrend() {
+        if (this.ringBuffer.length < 3) {
+            return { trend: 'stable', ratePerMin: 0 };
+        }
+        const readings = this.ringBuffer.slice(-TREND_WINDOW);
+        const n = readings.length;
+        const firstTs = readings[0].timestamp;
+        const xs = readings.map(r => (r.timestamp - firstTs) / 1000);
+        const ys = readings.map(r => r.pressurePercent);
+        const sumX = xs.reduce((a, b) => a + b, 0);
+        const sumY = ys.reduce((a, b) => a + b, 0);
+        const sumXY = xs.reduce((a, x, i) => a + x * ys[i], 0);
+        const sumX2 = xs.reduce((a, x) => a + x * x, 0);
+        const denom = n * sumX2 - sumX * sumX;
+        if (denom === 0)
+            return { trend: 'stable', ratePerMin: 0 };
+        const slope = (n * sumXY - sumX * sumY) / denom;
+        const ratePerMin = slope * 60;
+        let trend;
+        if (ratePerMin > 0.5)
+            trend = 'rising';
+        else if (ratePerMin < -0.5)
+            trend = 'falling';
+        else
+            trend = 'stable';
+        return { trend, ratePerMin };
+    }
+}
+//# sourceMappingURL=MemoryPressureMonitor.js.map

package/dist/server/routes.js

@@ -63,6 +63,15 @@ export function createRoutes(ctx) {
                 heapUsed: Math.round(mem.heapUsed / 1024 / 1024),
                 heapTotal: Math.round(mem.heapTotal / 1024 / 1024),
             };
+            // System-wide memory state
+            const os = require('node:os');
+            const totalMem = os.totalmem();
+            const freeMem = os.freemem();
+            base.systemMemory = {
+                totalGB: Math.round(totalMem / (1024 ** 3) * 10) / 10,
+                freeGB: Math.round(freeMem / (1024 ** 3) * 10) / 10,
+                usedPercent: Math.round(((totalMem - freeMem) / totalMem) * 1000) / 10,
+            };
             // Job health summary
             if (ctx.scheduler) {
                 const jobs = ctx.scheduler.getJobs();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.7.45",
+  "version": "0.7.46",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",