instar 0.7.49 → 0.7.51

package/dist/core/UpdateChecker.js

@@ -226,9 +226,11 @@ export class UpdateChecker {
         }
     }
     /**
-     * Fetch human-readable changelog from GitHub releases.
+     * Fetch human-readable changelog from GitHub releases, falling back to
+     * recent commit messages if no release exists for this version.
      */
     async fetchChangelog(version) {
+        // Try GitHub release first
         try {
             const tag = version.startsWith('v') ? version : `v${version}`;
             const response = await fetch(`${GITHUB_RELEASES_URL}/tags/${tag}`, {
@@ -238,16 +240,41 @@ export class UpdateChecker {
                 },
                 signal: AbortSignal.timeout(10000),
             });
-            if (!response.ok)
-                return undefined;
-            const release = await response.json();
-            if (release.body) {
-                // Truncate to first 500 chars for concise summary
-                const summary = release.body.slice(0, 500);
-                return summary.length < release.body.length ? summary + '...' : summary;
+            if (response.ok) {
+                const release = await response.json();
+                if (release.body) {
+                    const summary = release.body.slice(0, 500);
+                    return summary.length < release.body.length ? summary + '...' : summary;
+                }
+                if (release.name)
+                    return release.name;
+            }
+        }
+        catch {
+            // Non-critical — try commit fallback
+        }
+        // Fallback: fetch recent commits from GitHub
+        try {
+            const response = await fetch('https://api.github.com/repos/SageMindAI/instar/commits?per_page=5', {
+                headers: {
+                    'Accept': 'application/vnd.github.v3+json',
+                    'User-Agent': 'instar-update-checker',
+                },
+                signal: AbortSignal.timeout(10000),
+            });
+            if (response.ok) {
+                const commits = await response.json();
+                if (commits.length > 0) {
+                    const lines = commits
+                        .map(c => {
+                        // Take first line of commit message only
+                        const firstLine = c.commit.message.split('\n')[0];
+                        return `• ${firstLine}`;
+                    })
+                        .join('\n');
+                    return `Recent changes:\n${lines}`;
+                }
             }
-            if (release.name)
-                return release.name;
         }
         catch {
             // Non-critical

package/dist/core/types.d.ts

@@ -712,6 +712,14 @@ export interface MonitoringConfig {
     memoryMonitoring: boolean;
     /** Health check interval in ms */
     healthCheckIntervalMs: number;
+    /** Session watchdog — auto-remediation for stuck commands */
+    watchdog?: {
+        enabled: boolean;
+        /** Seconds before a command is considered stuck (default: 180) */
+        stuckCommandSec?: number;
+        /** Poll interval in ms (default: 30000) */
+        pollIntervalMs?: number;
+    };
 }
 /** @deprecated Use InstarConfig instead */
 export type AgentKitConfig = InstarConfig;

package/dist/lifeline/ServerSupervisor.d.ts

@@ -25,6 +25,8 @@ export declare class ServerSupervisor extends EventEmitter {
     private restartBackoffMs;
     private isRunning;
     private lastHealthy;
+    private startupGraceMs;
+    private spawnedAt;
     constructor(options: {
         projectDir: string;
         projectName: string;

package/dist/lifeline/ServerSupervisor.js

@@ -22,6 +22,8 @@ export class ServerSupervisor extends EventEmitter {
     restartBackoffMs = 5000;
     isRunning = false;
     lastHealthy = 0;
+    startupGraceMs = 20_000; // 20 seconds grace period after spawn before health checks
+    spawnedAt = 0;
     constructor(options) {
         super();
         this.projectDir = options.projectDir;
@@ -95,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, "'\\''")}'`)
@@ -108,6 +110,7 @@ export class ServerSupervisor extends EventEmitter {
             ], { stdio: 'ignore' });
             console.log(`[Supervisor] Server started in tmux session: ${this.serverSessionName}`);
             this.isRunning = true;
+            this.spawnedAt = Date.now();
             this.startHealthChecks();
             return true;
         }
@@ -133,6 +136,10 @@ export class ServerSupervisor extends EventEmitter {
         if (this.healthCheckInterval)
             return;
         this.healthCheckInterval = setInterval(async () => {
+            // Skip health checks during startup grace period — server needs time to boot
+            if (this.spawnedAt > 0 && (Date.now() - this.spawnedAt) < this.startupGraceMs) {
+                return;
+            }
             try {
                 const healthy = await this.checkHealth();
                 if (healthy) {

package/dist/lifeline/TelegramLifeline.d.ts

@@ -30,6 +30,7 @@ export declare class TelegramLifeline {
     private stopHeartbeat;
     private replayInterval;
     private lifelineTopicId;
+    private lockPath;
     constructor(projectDir?: string);
     /**
      * Start the lifeline — begins Telegram polling and server supervision.
@@ -44,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,12 +19,61 @@
  * 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';
+/**
+ * Acquire an exclusive lock file to prevent multiple lifeline instances.
+ * Returns true if lock acquired, false if another instance holds it.
+ */
+function acquireLockFile(lockPath) {
+    try {
+        // Check if lock file exists and if the PID is still alive
+        if (fs.existsSync(lockPath)) {
+            const raw = fs.readFileSync(lockPath, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data.pid && typeof data.pid === 'number') {
+                try {
+                    // Signal 0 checks if process exists without killing it
+                    process.kill(data.pid, 0);
+                    // Process still alive — another lifeline is running
+                    return false;
+                }
+                catch {
+                    // Process is dead — stale lock, we can take over
+                    console.log(`[Lifeline] Removing stale lock (PID ${data.pid} is dead)`);
+                }
+            }
+        }
+        // Write our PID
+        const tmpPath = `${lockPath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+        fs.renameSync(tmpPath, lockPath);
+        return true;
+    }
+    catch (err) {
+        console.error(`[Lifeline] Lock acquisition failed: ${err}`);
+        return false;
+    }
+}
+function releaseLockFile(lockPath) {
+    try {
+        if (fs.existsSync(lockPath)) {
+            const raw = fs.readFileSync(lockPath, 'utf-8');
+            const data = JSON.parse(raw);
+            // Only remove if we own it
+            if (data.pid === process.pid) {
+                fs.unlinkSync(lockPath);
+            }
+        }
+    }
+    catch { /* best effort */ }
+}
 export class TelegramLifeline {
     config;
     projectConfig;
@@ -37,6 +86,7 @@ export class TelegramLifeline {
     stopHeartbeat = null;
     replayInterval = null;
     lifelineTopicId = null;
+    lockPath;
     constructor(projectDir) {
         this.projectConfig = loadConfig(projectDir);
         ensureStateDir(this.projectConfig.stateDir);
@@ -48,6 +98,7 @@ export class TelegramLifeline {
         this.config = telegramConfig.config;
         this.queue = new MessageQueue(this.projectConfig.stateDir);
         this.offsetPath = path.join(this.projectConfig.stateDir, 'lifeline-poll-offset.json');
+        this.lockPath = path.join(this.projectConfig.stateDir, 'lifeline.lock');
         this.supervisor = new ServerSupervisor({
             projectDir: this.projectConfig.projectDir,
             projectName: this.projectConfig.projectName,
@@ -75,6 +126,11 @@ export class TelegramLifeline {
         console.log(`  Port: ${this.projectConfig.port}`);
         console.log(`  State: ${this.projectConfig.stateDir}`);
         console.log();
+        // 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 will restart after ThrottleInterval, acting as a watchdog
+        }
         // Register in port registry (lifeline owns the port claim)
         try {
             registerPort(`${this.projectConfig.projectName}-lifeline`, this.projectConfig.port + 1000, // Lifeline uses port + 1000 to avoid conflict
@@ -112,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...');
@@ -123,6 +192,7 @@ export class TelegramLifeline {
             if (this.stopHeartbeat)
                 this.stopHeartbeat();
             unregisterPort(`${this.projectConfig.projectName}-lifeline`);
+            releaseLockFile(this.lockPath);
             await this.supervisor.stop();
             process.exit(0);
         };
@@ -326,6 +396,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

@@ -7,13 +7,15 @@
 import type { SessionManager } from '../core/SessionManager.js';
 import type { JobScheduler } from '../scheduler/JobScheduler.js';
 import type { HealthStatus, InstarConfig } from '../core/types.js';
+import type { SessionWatchdog } from './SessionWatchdog.js';
 export declare class HealthChecker {
     private config;
     private sessionManager;
     private scheduler;
+    private watchdog;
     private checkInterval;
     private lastStatus;
-    constructor(config: InstarConfig, sessionManager: SessionManager, scheduler?: JobScheduler | null);
+    constructor(config: InstarConfig, sessionManager: SessionManager, scheduler?: JobScheduler | null, watchdog?: SessionWatchdog | null);
     /**
      * Run all health checks and return aggregated status.
      */
@@ -33,6 +35,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

@@ -11,12 +11,14 @@ export class HealthChecker {
     config;
     sessionManager;
     scheduler;
+    watchdog;
     checkInterval = null;
     lastStatus = null;
-    constructor(config, sessionManager, scheduler = null) {
+    constructor(config, sessionManager, scheduler = null, watchdog = null) {
         this.config = config;
         this.sessionManager = sessionManager;
         this.scheduler = scheduler;
+        this.watchdog = watchdog;
     }
     /**
      * Run all health checks and return aggregated status.
@@ -26,9 +28,21 @@ 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();
         }
+        if (this.watchdog) {
+            const wdStatus = this.watchdog.getStatus();
+            const intervening = wdStatus.sessions.filter(s => s.escalation && s.escalation.level > 0);
+            components.watchdog = {
+                status: intervening.length > 0 ? 'degraded' : 'healthy',
+                message: intervening.length > 0
+                    ? `Intervening on ${intervening.length} session(s)`
+                    : `Monitoring${wdStatus.enabled ? '' : ' (disabled)'}`,
+                lastCheck: new Date().toISOString(),
+            };
+        }
         // Aggregate: worst component status becomes overall status
         const statuses = Object.values(components).map(c => c.status);
         let overall = 'healthy';
@@ -135,6 +149,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