instar 0.7.49 → 0.7.50

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);
         };
@@ -171,23 +241,8 @@ export class TelegramLifeline {
         // Forward to server if healthy
         if (this.supervisor.healthy) {
             const forwarded = await this.forwardToServer(topicId, text, msg);
-            if (forwarded) {
-                // Delivery confirmation — user knows message reached the server
-                await this.sendToTopic(topicId, '✓ Delivered');
+            if (forwarded)
                 return;
-            }
-            // Server appears healthy but forward failed — queue with accurate message
-            this.queue.enqueue({
-                id: `tg-${msg.message_id}`,
-                topicId,
-                text,
-                fromUserId: msg.from.id,
-                fromUsername: msg.from.username,
-                fromFirstName: msg.from.first_name,
-                timestamp: new Date(msg.date * 1000).toISOString(),
-            });
-            await this.sendToTopic(topicId, `Server is restarting. Your message has been queued (${this.queue.length} in queue). It will be delivered when the server recovers.`);
-            return;
         }
         // Server is down — queue the message
         this.queue.enqueue({
@@ -326,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/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/middleware.js

@@ -32,6 +32,11 @@ export function authMiddleware(authToken) {
             next();
             return;
         }
+        // Internal endpoints are localhost-only (server binds 127.0.0.1) — skip auth
+        if (req.path.startsWith('/internal/')) {
+            next();
+            return;
+        }
         // View routes support signed URLs for browser access (see ?sig= below)
         if (req.path.startsWith('/view/') && req.method === 'GET') {
             const sig = typeof req.query.sig === 'string' ? req.query.sig : null;