instar 0.7.52 → 0.7.53

package/dist/commands/server.js

@@ -36,6 +36,7 @@ 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 { SessionWatchdog } from '../monitoring/SessionWatchdog.js';
 import { installAutoStart } from './setup.js';
 /**
  * Check if autostart is installed for this project.
@@ -646,6 +647,31 @@ export async function startServer(options) {
                 scheduler.notifyJobComplete(session.id, session.tmuxSession);
             });
         }
+        // Session Watchdog — auto-remediation for stuck commands
+        let watchdog;
+        if (config.monitoring.watchdog?.enabled) {
+            watchdog = new SessionWatchdog(config, sessionManager, state);
+            watchdog.on('intervention', (event) => {
+                if (telegram) {
+                    const topicId = telegram.getTopicForSession(event.sessionName);
+                    if (topicId) {
+                        const levelNames = ['Monitoring', 'Ctrl+C', 'SIGTERM', 'SIGKILL', 'Kill Session'];
+                        const levelName = levelNames[event.level] || `Level ${event.level}`;
+                        telegram.sendToTopic(topicId, `🔧 Watchdog [${levelName}]: ${event.action}\nStuck: \`${event.stuckCommand.slice(0, 60)}\``).catch(() => { });
+                    }
+                }
+            });
+            watchdog.on('recovery', (sessionName, fromLevel) => {
+                if (telegram) {
+                    const topicId = telegram.getTopicForSession(sessionName);
+                    if (topicId) {
+                        telegram.sendToTopic(topicId, `✅ Watchdog: session recovered (was at escalation level ${fromLevel})`).catch(() => { });
+                    }
+                }
+            });
+            watchdog.start();
+            console.log(pc.green('  Session Watchdog enabled'));
+        }
         // Set up feedback and update checking
         let feedback;
         if (config.feedback) {
@@ -800,7 +826,7 @@ export async function startServer(options) {
             }
         });
         sleepWakeDetector.start();
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, publisher, viewer, tunnel, evolution });
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, publisher, viewer, tunnel, evolution, watchdog });
         await server.start();
         // Start tunnel AFTER server is listening
         if (tunnel) {

package/dist/core/AutoUpdater.js

@@ -54,17 +54,11 @@ export class AutoUpdater {
         if (this.interval)
             return;
         const intervalMs = this.config.checkIntervalMinutes * 60 * 1000;
-        // Detect npx cache — auto-apply and restart cause infinite loops when
-        // running from npx because the cache still resolves to the old version
-        // after npm installs the update. The restart finds the update again,
-        // applies it again, restarts again — forever, killing all sessions each time.
+        // Warn if running from npx cache (auto-updates won't work properly)
         const scriptPath = process.argv[1] || '';
-        const runningFromNpx = scriptPath.includes('.npm/_npx') || scriptPath.includes('/_npx/');
-        if (runningFromNpx) {
-            this.config.autoApply = false;
-            this.config.autoRestart = false;
-            console.warn('[AutoUpdater] Running from npx cache. Auto-apply and auto-restart disabled to prevent restart loops.\n' +
-                '[AutoUpdater] Run: npm install -g instar  (then restart with: instar server start)');
+        if (scriptPath.includes('.npm/_npx') || scriptPath.includes('/_npx/')) {
+            console.warn('[AutoUpdater] WARNING: Running from npx cache. Auto-updates require a global install.\n' +
+                '[AutoUpdater] Run: npm install -g instar');
         }
         console.log(`[AutoUpdater] Started (every ${this.config.checkIntervalMinutes}m, ` +
             `autoApply: ${this.config.autoApply}, autoRestart: ${this.config.autoRestart})`);
@@ -128,7 +122,8 @@ export class AutoUpdater {
             if (!this.config.autoApply) {
                 // Just notify — don't apply
                 await this.notify(`Update available: v${info.currentVersion} → v${info.latestVersion}\n\n` +
-                    (info.changeSummary ? `Changes: ${info.changeSummary}\n\n` : '') +
+                    (info.changeSummary ? `What changed:\n${info.changeSummary}\n\n` : '') +
+                    `Details: ${info.changelogUrl || 'https://github.com/SageMindAI/instar/releases'}\n\n` +
                     `Auto-apply is disabled. Apply manually:\n` +
                     `curl -X POST http://localhost:${this.getPort()}/updates/apply`);
                 return;
@@ -153,13 +148,19 @@ export class AutoUpdater {
             console.log(`[AutoUpdater] Updated: v${result.previousVersion} → v${result.newVersion}`);
             // Step 5: Notify via Telegram
             const restartNote = result.restartNeeded && this.config.autoRestart
-                ? 'Server is restarting now...'
+                ? '\nServer is restarting now...'
                 : result.restartNeeded
-                    ? 'A server restart is needed to use the new version.'
+                    ? '\nA server restart is needed to use the new version.'
                     : '';
+            const changeSummary = info.changeSummary
+                ? `What changed:\n${info.changeSummary}\n`
+                : '';
+            const detailsUrl = info.changelogUrl || 'https://github.com/SageMindAI/instar/releases';
             await this.notify(`Updated: v${result.previousVersion} → v${result.newVersion}\n\n` +
-                (info.changeSummary ? `What changed:\n${info.changeSummary}\n\n` : '') +
-                restartNote);
+                changeSummary +
+                `Details: ${detailsUrl}\n` +
+                restartNote +
+                `\n\nTo disable auto-updates, set "autoApply": false in .instar/config.json under "updates".`);
             // Step 6: Self-restart if needed and configured
             if (result.restartNeeded && this.config.autoRestart) {
                 // Brief delay to let the Telegram notification send
@@ -206,6 +207,23 @@ export class AutoUpdater {
             }
         }
         catch { /* not found globally */ }
+        // If `which instar` didn't find a global binary, try npm's prefix path directly.
+        // This handles the common case where npm's global bin directory is not in PATH
+        // (automation contexts, fresh shell sessions, custom npm prefixes).
+        if (!instarBin) {
+            try {
+                const npmPrefix = execFileSync('npm', ['prefix', '-g'], {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                const candidate = `${npmPrefix}/bin/instar`;
+                if (fs.existsSync(candidate)) {
+                    instarBin = candidate;
+                    console.log(`[AutoUpdater] Found global binary via npm prefix: ${instarBin}`);
+                }
+            }
+            catch { /* npm not available or prefix lookup failed */ }
+        }
         let cmd;
         if (instarBin) {
             // Use the global binary — guaranteed to be the updated version
@@ -214,7 +232,21 @@ export class AutoUpdater {
             console.log(`[AutoUpdater] Will restart from global binary: ${instarBin}`);
         }
         else {
-            // Fallback: use the original process.argv (global not available)
+            // No global binary found. If we were running from npx cache, restarting
+            // from process.argv would loop (npx cache is the old version, which would
+            // detect the update again and restart again indefinitely).
+            const scriptPath = process.argv[1] || '';
+            const isNpxCache = scriptPath.includes('.npm/_npx') || scriptPath.includes('/_npx/');
+            if (isNpxCache) {
+                console.error('[AutoUpdater] Update applied but cannot restart — global binary not found in PATH or npm prefix.');
+                console.error('[AutoUpdater] Restarting from npx cache would cause a restart loop.');
+                console.error('[AutoUpdater] Manual restart required: npm install -g instar && instar server start');
+                void this.notify('Update applied but auto-restart skipped — global binary not in PATH.\n\n' +
+                    'Run manually to activate the update:\n' +
+                    '```\nnpm install -g instar\ninstar server start --foreground\n```');
+                return;
+            }
+            // Not from npx cache — safe to restart from current path
             const args = process.argv.slice(1)
                 .map(a => `'${a.replace(/'/g, "'\\''")}'`)
                 .join(' ');

package/dist/core/SessionManager.d.ts

@@ -68,6 +68,12 @@ export declare class SessionManager extends EventEmitter {
      * Send input to a running tmux session.
      */
     sendInput(tmuxSession: string, input: string): boolean;
+    /**
+     * Send a tmux key sequence (without -l literal flag).
+     * Use for special keys like 'C-c' (Ctrl+C), 'Enter', 'Escape'.
+     * Unlike sendInput() which uses -l (literal), this sends key names directly.
+     */
+    sendKey(tmuxSession: string, key: string): boolean;
     /**
      * List all sessions that are currently running.
      * Pure filter — does not mutate state. The monitor tick handles lifecycle transitions.

package/dist/core/SessionManager.js

@@ -297,6 +297,20 @@ export class SessionManager extends EventEmitter {
             return false;
         }
     }
+    /**
+     * Send a tmux key sequence (without -l literal flag).
+     * Use for special keys like 'C-c' (Ctrl+C), 'Enter', 'Escape'.
+     * Unlike sendInput() which uses -l (literal), this sends key names directly.
+     */
+    sendKey(tmuxSession, key) {
+        try {
+            execFileSync(this.config.tmuxPath, ['send-keys', '-t', `=${tmuxSession}:`, key], { encoding: 'utf-8', timeout: 5000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * List all sessions that are currently running.
      * Pure filter — does not mutate state. The monitor tick handles lifecycle transitions.
@@ -464,35 +478,25 @@ export class SessionManager extends EventEmitter {
         const exactTarget = `=${tmuxSession}:`;
         try {
             if (text.includes('\n')) {
-                // Multi-line: write to temp file, load into tmux buffer, paste into pane.
+                // Multi-line: pipe into tmux load-buffer via stdin, then paste into pane.
                 // This avoids newlines being treated as Enter keypresses which would
                 // fragment the message into multiple Claude prompts.
-                const tmpDir = path.join('/tmp', 'instar-inject');
-                fs.mkdirSync(tmpDir, { recursive: true });
-                const tmpPath = path.join(tmpDir, `msg-${Date.now()}-${process.pid}.txt`);
-                fs.writeFileSync(tmpPath, text);
-                try {
-                    execFileSync(this.config.tmuxPath, ['load-buffer', tmpPath], {
-                        encoding: 'utf-8', timeout: 5000,
-                    });
-                    execFileSync(this.config.tmuxPath, ['paste-buffer', '-t', exactTarget, '-p'], {
-                        encoding: 'utf-8', timeout: 5000,
-                    });
-                    // Brief delay to let the terminal process the paste before sending Enter.
-                    // Without this, the Enter arrives before paste processing completes and
-                    // the message sits in the input buffer without being submitted.
-                    execFileSync('/bin/sleep', ['0.3'], { timeout: 2000 });
-                    // Send Enter to submit
-                    execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
-                        encoding: 'utf-8', timeout: 5000,
-                    });
-                }
-                finally {
-                    try {
-                        fs.unlinkSync(tmpPath);
-                    }
-                    catch { /* ignore */ }
-                }
+                // Uses stdin pipe (load-buffer -) instead of temp files to avoid
+                // macOS TCC "access data from other apps" permission prompts.
+                execFileSync(this.config.tmuxPath, ['load-buffer', '-'], {
+                    encoding: 'utf-8', timeout: 5000, input: text,
+                });
+                execFileSync(this.config.tmuxPath, ['paste-buffer', '-t', exactTarget, '-p'], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
+                // Brief delay to let the terminal process the paste before sending Enter.
+                // Without this, the Enter arrives before paste processing completes and
+                // the message sits in the input buffer without being submitted.
+                execFileSync('/bin/sleep', ['0.3'], { timeout: 2000 });
+                // Send Enter to submit
+                execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
             }
             else {
                 // Single-line: simple send-keys

package/dist/core/UpdateChecker.d.ts

@@ -60,7 +60,8 @@ export declare class UpdateChecker {
         updatedAt: string;
     } | null;
     /**
-     * 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.
      */
     fetchChangelog(version: string): Promise<string | undefined>;
     /**

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/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.
      */

package/dist/monitoring/HealthChecker.js

@@ -6,17 +6,20 @@
  */
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 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.
@@ -30,6 +33,17 @@ export class HealthChecker {
         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';
@@ -139,7 +153,6 @@ export class HealthChecker {
     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);

package/dist/monitoring/SessionWatchdog.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SessionWatchdog — Auto-remediation for stuck Claude sessions (Instar port).
+ *
+ * Detects when a Claude session has a long-running bash command and escalates
+ * from gentle (Ctrl+C) to forceful (SIGKILL + session kill). Adapted from
+ * Dawn Server's SessionWatchdog for Instar's self-contained architecture.
+ *
+ * Escalation pipeline:
+ *   Level 0: Monitoring (default)
+ *   Level 1: Ctrl+C via tmux send-keys
+ *   Level 2: SIGTERM the stuck child PID
+ *   Level 3: SIGKILL the stuck child PID
+ *   Level 4: Kill tmux session
+ */
+import { EventEmitter } from 'node:events';
+import type { SessionManager } from '../core/SessionManager.js';
+import type { StateManager } from '../core/StateManager.js';
+import type { InstarConfig } from '../core/types.js';
+export declare enum EscalationLevel {
+    Monitoring = 0,
+    CtrlC = 1,
+    SigTerm = 2,
+    SigKill = 3,
+    KillSession = 4
+}
+interface EscalationState {
+    level: EscalationLevel;
+    levelEnteredAt: number;
+    stuckChildPid: number;
+    stuckCommand: string;
+    retryCount: number;
+}
+export interface InterventionEvent {
+    sessionName: string;
+    level: EscalationLevel;
+    action: string;
+    stuckCommand: string;
+    stuckPid: number;
+    timestamp: number;
+}
+export interface WatchdogEvents {
+    intervention: [event: InterventionEvent];
+    recovery: [sessionName: string, fromLevel: EscalationLevel];
+}
+export declare class SessionWatchdog extends EventEmitter {
+    private config;
+    private sessionManager;
+    private state;
+    private interval;
+    private escalationState;
+    private interventionHistory;
+    private enabled;
+    private running;
+    private stuckThresholdMs;
+    private pollIntervalMs;
+    constructor(config: InstarConfig, sessionManager: SessionManager, state: StateManager);
+    start(): void;
+    stop(): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    isManaging(sessionName: string): boolean;
+    getStatus(): {
+        enabled: boolean;
+        sessions: Array<{
+            name: string;
+            escalation: EscalationState | null;
+        }>;
+        interventionHistory: InterventionEvent[];
+    };
+    private poll;
+    private checkSession;
+    private handleEscalation;
+    private getClaudePid;
+    private getChildProcesses;
+    private isExcluded;
+    private parseElapsed;
+    private sendSignal;
+    private isProcessAlive;
+    private killTmuxSession;
+    private recordIntervention;
+}
+export {};
+//# sourceMappingURL=SessionWatchdog.d.ts.map