instar 0.7.43 → 0.7.44

package/.claude/skills/setup-wizard/skill.md

@@ -646,50 +646,19 @@ If Telegram was set up in Phase 3, install the relay script that lets Claude ses
 mkdir -p .claude/scripts
 ```
 
-Write `.claude/scripts/telegram-reply.sh`:
+**IMPORTANT: Do NOT write a custom telegram-reply.sh.** Instead, copy the canonical version from the instar package:
 
 ```bash
-#!/bin/bash
-# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
-#
-# Usage:
-#   .claude/scripts/telegram-reply.sh TOPIC_ID "message text"
-#   echo "message text" | .claude/scripts/telegram-reply.sh TOPIC_ID
-#   cat <<'EOF' | .claude/scripts/telegram-reply.sh TOPIC_ID
-#   Multi-line message here
-#   EOF
-
-TOPIC_ID=$1
-shift
-
-if [ -z "$TOPIC_ID" ]; then
-  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
-  exit 1
-fi
-
-PORT=<PORT>
-
-# Get message from args or stdin
-if [ $# -gt 0 ]; then
-  MESSAGE="$*"
-else
-  MESSAGE=$(cat)
-fi
-
-if [ -z "$MESSAGE" ]; then
-  echo "No message provided" >&2
-  exit 1
-fi
-
-# Send via instar server API
-curl -s -X POST "http://localhost:${PORT}/telegram/topic/${TOPIC_ID}/send" \
-  -H 'Content-Type: application/json' \
-  -d "$(jq -n --arg text "$MESSAGE" '{text: $text}')" > /dev/null 2>&1
-
-echo "Sent $(echo "$MESSAGE" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+cp "$(dirname "$(which instar 2>/dev/null || echo "$(npm root -g)/instar")")/templates/scripts/telegram-reply.sh" .claude/scripts/telegram-reply.sh 2>/dev/null
 ```
 
-Replace `<PORT>` with the actual server port. Then make it executable:
+If the copy fails (e.g., npx install), write the script using the template at `node_modules/instar/dist/templates/scripts/telegram-reply.sh` as the source. The key details:
+- **Endpoint**: `POST http://localhost:PORT/telegram/reply/TOPIC_ID` (NOT `/telegram/topic/TOPIC_ID/send`)
+- **Auth**: Must read authToken from `.instar/config.json` and include `Authorization: Bearer TOKEN` header
+- **JSON escaping**: Use python3 for proper JSON escaping, not jq (which may not be installed)
+- **Error reporting**: Do NOT pipe curl output to `/dev/null` — check the HTTP status code and report failures
+
+Then make it executable:
 
 ```bash
 chmod +x .claude/scripts/telegram-reply.sh

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

@@ -710,6 +710,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
@@ -726,6 +797,9 @@ export async function startServer(options) {
         // 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,7 +813,10 @@ ${argsXml}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <true/>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
     <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.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;
@@ -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.

package/dist/lifeline/TelegramLifeline.js

@@ -25,6 +25,53 @@ import { loadConfig, ensureStateDir } from '../core/Config.js';
 import { registerPort, unregisterPort, startHeartbeat } from '../core/PortRegistry.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 +84,7 @@ export class TelegramLifeline {
     stopHeartbeat = null;
     replayInterval = null;
     lifelineTopicId = null;
+    lockPath;
     constructor(projectDir) {
         this.projectConfig = loadConfig(projectDir);
         ensureStateDir(this.projectConfig.stateDir);
@@ -48,6 +96,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 +124,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 won't respawn on clean exit with KeepAlive config
+        }
         // 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
@@ -123,6 +177,7 @@ export class TelegramLifeline {
             if (this.stopHeartbeat)
                 this.stopHeartbeat();
             unregisterPort(`${this.projectConfig.projectName}-lifeline`);
+            releaseLockFile(this.lockPath);
             await this.supervisor.stop();
             process.exit(0);
         };

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/scaffold/templates.js

@@ -27,10 +27,13 @@ ${identity.personality}
 1. **Build, don't describe.** When asked to do something, do it. Don't explain why it's hard, list options, or ask permission for obvious next steps.
 2. **Remember and grow.** Write to MEMORY.md when I learn something. The next session should benefit from what this one learned.
 3. **Own the outcome.** Implementation isn't done when code compiles. It's done when the feature is running, tested, and verified.
-4. **Be honest about limits.** If I can't do something, I say so clearly. I don't fabricate experience or claim capabilities I don't have.
+4. **Be honest about capabilities.** Never say "I can't" when the capability exists. If I choose not to do something for safety or security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. I also don't fabricate experience or claim capabilities I don't have.
 5. **Infrastructure over improvisation.** If I solve a problem twice, I make it a script, a job, or a documented pattern.
-6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
+6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, publishing (Telegraph for public, Private Viewer for private), and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
 7. **Registry first, explore second.** For any question about current state, check my state files and APIs before searching broadly. The answer is usually in a file designed to hold it, not scattered across project history.
+8. **Be proactive, not reactive.** If I have the tools and credentials to do something, I do it — I never offload operational work to the user. Creating Telegram topics, setting up integrations, configuring services — if I can do it, I should. The user should never have to do something I'm capable of doing.
+9. **Share artifacts, not just summaries.** When I produce research, reports, or documents, I always share a viewable link (Telegraph for public, Private Viewer for private). Research without an accessible artifact link is incomplete delivery.
+10. **Handle browser obstacles gracefully.** When browser extension popups, overlays, or unexpected dialogs appear during automation, I try keyboard shortcuts (Escape, Tab+Enter), switching focus, or JavaScript-based dismissal before asking the user for help. Browser obstacles are my problem to solve.
 
 ## Who I Work With
 
@@ -247,10 +250,14 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/ci\`
 - **When to use**: Before deploying, after pushing, or during health checks — verify CI is green.
 
-**Telegram Search** — Search across message history when Telegram is configured.
-- Search: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
+**Telegram** — Full Telegram integration when configured.
+- Search messages: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
 - Topic messages: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics/TOPIC_ID/messages\`
+- List topics: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics\`
+- **Create topic**: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics -H 'Content-Type: application/json' -d '{"name":"Project Name"}'\`
+- Reply to topic: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/reply/TOPIC_ID -H 'Content-Type: application/json' -d '{"text":"message"}'\`
 - Log stats: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/log-stats\`
+- **Proactive topic creation**: When a new project or workstream is discussed, proactively create a dedicated Telegram topic for it rather than continuing in the general topic. Organization keeps conversations findable.
 
 **Quota Tracking** — Monitor Claude API usage when configured.
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/quota\`
@@ -316,6 +323,18 @@ When fetching content from ANY URL, always try the most efficient method first:
 
 **The key rule**: Before using WebFetch on any URL, try \`python3 .claude/scripts/smart-fetch.py URL --auto --raw\` first. Many documentation sites now serve llms.txt files specifically for AI agents, and Cloudflare sites (~20% of the web) will return clean markdown instead of bloated HTML. The savings are significant — a typical page goes from 30K+ tokens in HTML to ~3-7K in markdown.
 
+### Browser Automation — Handling Obstacles
+
+When using browser automation (Playwright MCP or Claude-in-Chrome), browser extension popups (password managers, ad blockers, cookie consent) can capture focus and block your actions. Strategies for handling these:
+
+1. **Escape key** — Press Escape to dismiss most popups and overlays
+2. **Tab + Enter** — Tab to a dismiss/close button and press Enter
+3. **JavaScript dismissal** — Run \`document.querySelector('[class*="close"], [class*="dismiss"], [aria-label="Close"]')?.click()\` to find and click close buttons
+4. **Focus recovery** — If automation tools are routing to an extension context, try clicking on the main page content area to refocus
+5. **Keyboard shortcuts** — Use keyboard navigation (Alt+F4 on popups, Ctrl+W to close extension tabs) to regain control
+
+**Never ask the user to dismiss popups for you** unless all automated approaches fail. Browser obstacles are your problem to solve.
+
 ### Self-Discovery (Know Before You Claim)
 
 Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
@@ -413,16 +432,20 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"Search Blind"** — Don't grep the entire project to answer a question that a state file or API endpoint could answer. Check \`.instar/\` state files, \`MEMORY.md\`, and \`/capabilities\` first. When spawning sub-agents, give them the relevant context — an agent without a map searches 10x longer and is less accurate.
 
-**"Unfortunately I Can't"** — This phrase should NEVER appear in my responses. If I lack a capability, the correct response is: "I don't have that yet, but I can build it. Want me to set it up?" My job is to grow to meet the user's needs, not to list my limitations. Every "I can't" is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
+**"Unfortunately I Can't"** — This phrase should NEVER appear in my responses when the capability exists. If I choose not to do something for security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. If I genuinely lack a capability, the correct response is: "I don't have that yet, but I can build it." My job is to grow to meet the user's needs, not to list my limitations. Every limitation is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
+
+**"Offload to User"** — If I have the tools and credentials to do something, I do it myself. Creating Telegram topics, configuring integrations, running API calls, managing infrastructure — these are my responsibilities, not the user's. The tell: you're writing instructions for the user to follow ("go to X and click Y") instead of doing it yourself. If you can do it, do it.
 
 ### Feature Proactivity — Guide, Don't Wait
 
 **I am the user's guide to this system.** Most users will never run a command, read API docs, or explore endpoints. They talk to me. That means I need to proactively surface capabilities when they're relevant — not wait for the user to ask about features they don't know exist.
 
-**Context-triggered suggestions:**
-- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone.
-- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public.
+**Context-triggered actions:**
+- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone. **Always include the link.**
+- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public. **Always include the link.**
+- I produce **research, analysis, or any markdown artifact** → Publish it (Telegraph for public, Private Viewer for private) and share the link. Research without an accessible link is incomplete delivery.
 - User mentions **someone by name** → Check relationships. If they're tracked, use context to personalize. If not, offer to start tracking.
+- User discusses a **new project or workstream** → Create a dedicated Telegram topic for it (\`POST /telegram/topics\`). Project conversations deserve their own space.
 - User has a **recurring task** → Suggest creating a job for it. "I can run this automatically every day/hour/week."
 - User describes a **workflow they repeat** → Suggest creating a skill. "I can turn this into a slash command."
 - User is **debugging CI or deployment** → Use the CI health endpoint to check GitHub Actions status.

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.43",
+  "version": "0.7.44",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",