instar 0.7.32 → 0.7.34

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

@@ -32,6 +32,9 @@ import { PrivateViewer } from '../publishing/PrivateViewer.js';
 import { TunnelManager } from '../tunnel/TunnelManager.js';
 import { EvolutionManager } from '../core/EvolutionManager.js';
 import { QuotaTracker } from '../monitoring/QuotaTracker.js';
+import { AccountSwitcher } from '../monitoring/AccountSwitcher.js';
+import { QuotaNotifier } from '../monitoring/QuotaNotifier.js';
+import { classifySessionDeath } from '../monitoring/QuotaExhaustionDetector.js';
 /**
  * Respawn a session for a topic, including thread history in the bootstrap.
  * This prevents "thread drift" where respawned sessions lose context.
@@ -90,7 +93,7 @@ async function respawnSessionForTopic(sessionManager, telegram, targetSession, t
  * Wire up Telegram session management callbacks.
  * These enable /interrupt, /restart, /sessions commands and stall detection.
  */
-function wireTelegramCallbacks(telegram, sessionManager, state) {
+function wireTelegramCallbacks(telegram, sessionManager, state, quotaTracker, accountSwitcher, claudePath) {
     // /interrupt — send Escape key to a tmux session
     telegram.onInterruptSession = async (sessionName) => {
         try {
@@ -148,12 +151,165 @@ function wireTelegramCallbacks(telegram, sessionManager, state) {
         }
         return false;
     };
+    // /switch-account — swap active Claude Code account
+    if (accountSwitcher) {
+        telegram.onSwitchAccountRequest = async (target, replyTopicId) => {
+            try {
+                const result = await accountSwitcher.switchAccount(target);
+                await telegram.sendToTopic(replyTopicId, result.message);
+            }
+            catch (err) {
+                await telegram.sendToTopic(replyTopicId, `Account switch failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+    }
+    // /quota — show quota status
+    if (quotaTracker) {
+        telegram.onQuotaStatusRequest = async (replyTopicId) => {
+            try {
+                const quotaState = quotaTracker.getState();
+                if (!quotaState) {
+                    await telegram.sendToTopic(replyTopicId, 'No quota data available.');
+                    return;
+                }
+                const recommendation = quotaTracker.getRecommendation();
+                const lines = [
+                    `Weekly: ${quotaState.usagePercent}%`,
+                    quotaState.fiveHourPercent != null ? `5-Hour: ${quotaState.fiveHourPercent}%` : null,
+                    `Recommendation: ${recommendation}`,
+                    `Last updated: ${quotaState.lastUpdated}`,
+                ].filter(Boolean);
+                // Add account info if available
+                if (accountSwitcher) {
+                    const statuses = accountSwitcher.getAccountStatuses();
+                    if (statuses.length > 0) {
+                        lines.push('', 'Accounts:');
+                        for (const s of statuses) {
+                            const marker = s.isActive ? '→ ' : '  ';
+                            const stale = s.isStale ? ' (stale)' : '';
+                            const expired = s.tokenExpired ? ' (token expired)' : '';
+                            lines.push(`${marker}${s.name || s.email}: ${s.weeklyPercent}%${stale}${expired}`);
+                        }
+                    }
+                }
+                await telegram.sendToTopic(replyTopicId, lines.join('\n'));
+            }
+            catch (err) {
+                await telegram.sendToTopic(replyTopicId, `Failed to get quota: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+    }
+    // Classify session deaths for quota-aware stall detection
+    telegram.onClassifySessionDeath = async (sessionName) => {
+        try {
+            const output = sessionManager.captureOutput(sessionName, 100);
+            if (!output)
+                return null;
+            const quotaState = quotaTracker?.getState() ?? null;
+            const classification = classifySessionDeath(output, quotaState);
+            return { cause: classification.cause, detail: classification.detail };
+        }
+        catch {
+            return null;
+        }
+    };
+    // /login — seamless OAuth login flow
+    telegram.onLoginRequest = async (email, replyTopicId) => {
+        const tmuxPath = detectTmuxPath();
+        if (!tmuxPath) {
+            await telegram.sendToTopic(replyTopicId, 'tmux not found — cannot run login flow.');
+            return;
+        }
+        const loginSession = 'instar-login-flow';
+        try {
+            // Kill any existing login session
+            try {
+                execFileSync(tmuxPath, ['kill-session', '-t', `=${loginSession}`], { stdio: 'ignore' });
+            }
+            catch { /* not running */ }
+            // Start login command in tmux
+            const cliPath = claudePath || 'claude';
+            const loginCmd = email
+                ? `${cliPath} auth login --email "${email}"`
+                : `${cliPath} auth login`;
+            execFileSync(tmuxPath, ['new-session', '-d', '-s', loginSession, loginCmd], {
+                timeout: 10000,
+            });
+            await telegram.sendToTopic(replyTopicId, `Login flow started${email ? ` for ${email}` : ''}. Watching for OAuth URL...`);
+            // Poll for OAuth URL (up to 15 seconds)
+            let oauthUrl = null;
+            for (let i = 0; i < 30; i++) {
+                await new Promise(r => setTimeout(r, 500));
+                try {
+                    const output = sessionManager.captureOutput(loginSession, 50) || '';
+                    const urlMatch = output.match(/https:\/\/[^\s]+auth[^\s]*/i)
+                        || output.match(/https:\/\/[^\s]+login[^\s]*/i)
+                        || output.match(/https:\/\/[^\s]+oauth[^\s]*/i)
+                        || output.match(/https:\/\/console\.anthropic\.com[^\s]*/i);
+                    if (urlMatch) {
+                        oauthUrl = urlMatch[0];
+                        break;
+                    }
+                }
+                catch { /* retry */ }
+            }
+            if (!oauthUrl) {
+                await telegram.sendToTopic(replyTopicId, 'Could not detect OAuth URL. Check the login session manually.');
+                return;
+            }
+            await telegram.sendToTopic(replyTopicId, `Open this URL to authenticate:\n\n${oauthUrl}\n\nI'll detect when you're done.`);
+            // Poll for auth completion (up to 5 minutes)
+            let authComplete = false;
+            for (let i = 0; i < 300; i++) {
+                await new Promise(r => setTimeout(r, 1000));
+                try {
+                    const output = sessionManager.captureOutput(loginSession, 30) || '';
+                    const lower = output.toLowerCase();
+                    if (lower.includes('successfully') || lower.includes('authenticated') || lower.includes('logged in')) {
+                        authComplete = true;
+                        break;
+                    }
+                    // Detect "press Enter to continue" prompt
+                    if (lower.includes('press enter') || lower.includes('press any key')) {
+                        execFileSync(tmuxPath, ['send-keys', '-t', `=${loginSession}:`, 'Enter'], { timeout: 5000 });
+                        await new Promise(r => setTimeout(r, 2000));
+                        // Check if that completed it
+                        const finalOutput = sessionManager.captureOutput(loginSession, 30) || '';
+                        if (finalOutput.toLowerCase().includes('successfully') || finalOutput.toLowerCase().includes('authenticated')) {
+                            authComplete = true;
+                        }
+                        break;
+                    }
+                }
+                catch { /* retry */ }
+            }
+            // Clean up
+            try {
+                execFileSync(tmuxPath, ['kill-session', '-t', `=${loginSession}`], { stdio: 'ignore' });
+            }
+            catch { /* already ended */ }
+            if (authComplete) {
+                await telegram.sendToTopic(replyTopicId, 'Authentication successful! New sessions will use this account.');
+            }
+            else {
+                await telegram.sendToTopic(replyTopicId, 'Login flow ended. Check `claude auth status` to verify.');
+            }
+        }
+        catch (err) {
+            // Clean up on error
+            try {
+                execFileSync(tmuxPath, ['kill-session', '-t', `=${loginSession}`], { stdio: 'ignore' });
+            }
+            catch { /* ignore */ }
+            await telegram.sendToTopic(replyTopicId, `Login failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
 }
 /**
  * Wire up Telegram message routing: topic messages → Claude sessions.
  * This is the core handler that makes Telegram topics work like sessions.
  */
-function wireTelegramRouting(telegram, sessionManager) {
+function wireTelegramRouting(telegram, sessionManager, quotaTracker) {
     telegram.onTopicMessage = (msg) => {
         const topicId = msg.metadata?.messageThreadId ?? null;
         if (!topicId)
@@ -194,11 +350,27 @@ function wireTelegramRouting(telegram, sessionManager) {
                 telegram.trackMessageInjection(topicId, targetSession, text);
             }
             else {
-                // Session died — respawn with thread history
-                telegram.sendToTopic(topicId, `🔄 Session restarting — message queued.`).catch(() => { });
-                respawnSessionForTopic(sessionManager, telegram, targetSession, topicId, text).catch(err => {
-                    console.error(`[telegram→session] Respawn failed:`, err);
-                });
+                // Session died — check if it's a quota death before respawning
+                let isQuotaDeath = false;
+                try {
+                    const output = sessionManager.captureOutput(targetSession, 100);
+                    if (output) {
+                        const quotaState = quotaTracker?.getState() ?? null;
+                        const classification = classifySessionDeath(output, quotaState);
+                        if (classification.cause === 'quota_exhaustion' && classification.confidence !== 'low') {
+                            isQuotaDeath = true;
+                            telegram.sendToTopic(topicId, `🔴 Session died — quota limit reached.\n${classification.detail}\n\n` +
+                                `Use /switch-account to switch, /login to add an account, or reply again to force restart.`).catch(() => { });
+                        }
+                    }
+                }
+                catch { /* classification failed — fall through to respawn */ }
+                if (!isQuotaDeath) {
+                    telegram.sendToTopic(topicId, `🔄 Session restarting — message queued.`).catch(() => { });
+                    respawnSessionForTopic(sessionManager, telegram, targetSession, topicId, text).catch(err => {
+                        console.error(`[telegram→session] Respawn failed:`, err);
+                    });
+                }
             }
         }
         else {
@@ -417,9 +589,27 @@ export async function startServer(options) {
             telegram = new TelegramAdapter(telegramConfig.config, config.stateDir);
             await telegram.start();
             console.log(pc.green('  Telegram connected'));
+            // Set up account switcher (Keychain-based OAuth account swapping)
+            const accountSwitcher = new AccountSwitcher();
+            // Set up quota notifier (Telegram alerts on threshold crossings)
+            const quotaNotifier = new QuotaNotifier(config.stateDir);
+            const alertTopicId = state.get('agent-attention-topic') ?? null;
+            quotaNotifier.configure(async (topicId, text) => { await telegram.sendToTopic(topicId, text); }, alertTopicId);
+            // Periodic quota notification check (every 10 minutes)
+            if (quotaTracker) {
+                setInterval(() => {
+                    const quotaState = quotaTracker.getState();
+                    if (quotaState) {
+                        quotaNotifier.checkAndNotify(quotaState).catch(err => {
+                            console.error('[QuotaNotifier] Check failed:', err);
+                        });
+                    }
+                }, 10 * 60 * 1000);
+                console.log(pc.green('  Quota notifications enabled'));
+            }
             // Wire up topic → session routing and session management callbacks
-            wireTelegramRouting(telegram, sessionManager);
-            wireTelegramCallbacks(telegram, sessionManager, state);
+            wireTelegramRouting(telegram, sessionManager, quotaTracker);
+            wireTelegramCallbacks(telegram, sessionManager, state, quotaTracker, accountSwitcher, config.sessions.claudePath);
             console.log(pc.green('  Telegram message routing active'));
             if (scheduler) {
                 scheduler.setMessenger(telegram);

package/dist/commands/setup.js

@@ -420,26 +420,21 @@ async function runClassicSetup() {
     console.log(`  Auth token: ${pc.dim(authToken.slice(0, 8) + '...' + authToken.slice(-4))}`);
     console.log(`  ${pc.dim('(full token saved in .instar/config.json — use for API calls)')}`);
     console.log();
-    // Check if instar is globally installed (needed for server commands)
+    // Global install is required for auto-updates and persistent server commands.
+    // npx caches a snapshot that npm install -g doesn't touch, so agents
+    // installed only via npx can never auto-update.
     const isGloballyInstalled = isInstarGlobal();
     if (!isGloballyInstalled) {
-        console.log(pc.dim('  Tip: instar is not installed globally. For persistent server'));
-        console.log(pc.dim('  commands (start, stop, status), install it globally:'));
+        console.log(pc.dim('  Installing instar globally (required for auto-updates)...'));
         console.log();
-        const installGlobal = await confirm({
-            message: 'Install instar globally? (npm install -g instar)',
-            default: true,
-        });
-        if (installGlobal) {
-            try {
-                console.log(pc.dim('  Running: npm install -g instar'));
-                execFileSync('npm', ['install', '-g', 'instar'], { encoding: 'utf-8', stdio: 'inherit' });
-                console.log(`  ${pc.green('✓')} instar installed globally`);
-            }
-            catch {
-                console.log(pc.yellow('  Could not install globally. You can run it later:'));
-                console.log(`    ${pc.cyan('npm install -g instar')}`);
-            }
+        try {
+            execFileSync('npm', ['install', '-g', 'instar'], { encoding: 'utf-8', stdio: 'inherit' });
+            console.log(`  ${pc.green('✓')} instar installed globally`);
+        }
+        catch {
+            console.log(pc.yellow('  Could not install globally. Auto-updates will not work.'));
+            console.log(pc.yellow('  Please run manually:'));
+            console.log(`    ${pc.cyan('npm install -g instar')}`);
         }
         console.log();
     }

package/dist/core/AutoUpdater.js

@@ -17,7 +17,7 @@
  *   server process and exit. The new process binds to the port after
  *   the old one releases it during shutdown.
  */
-import { spawn } from 'node:child_process';
+import { spawn, execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 export class AutoUpdater {
@@ -54,6 +54,12 @@ export class AutoUpdater {
         if (this.interval)
             return;
         const intervalMs = this.config.checkIntervalMinutes * 60 * 1000;
+        // Warn if running from npx cache (auto-updates won't work properly)
+        const scriptPath = process.argv[1] || '';
+        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})`);
         // Run first check after a short delay (don't block startup)
@@ -179,13 +185,36 @@ export class AutoUpdater {
      */
     selfRestart() {
         console.log('[AutoUpdater] Initiating self-restart...');
-        // Build the command to restart
-        // process.argv[0] = node binary
-        // process.argv[1..] = CLI args (e.g., /path/to/cli.js server start --foreground)
-        const args = process.argv.slice(1)
-            .map(a => `'${a.replace(/'/g, "'\\''")}'`)
-            .join(' ');
-        const cmd = `sleep 2 && exec ${process.execPath} ${args}`;
+        // After an update, prefer the global binary (which has the new version)
+        // over process.argv (which may point to a stale npx cache).
+        // Extract non-path args (server, start, --foreground, --dir, etc.)
+        const cliArgs = process.argv.slice(2); // skip node + script path
+        let instarBin = null;
+        try {
+            const which = execFileSync('which', ['instar'], {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            if (which && !which.includes('.npm/_npx')) {
+                instarBin = which;
+            }
+        }
+        catch { /* not found globally */ }
+        let cmd;
+        if (instarBin) {
+            // Use the global binary — guaranteed to be the updated version
+            const quotedArgs = cliArgs.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ');
+            cmd = `sleep 2 && exec '${instarBin.replace(/'/g, "'\\''")}' ${quotedArgs}`;
+            console.log(`[AutoUpdater] Will restart from global binary: ${instarBin}`);
+        }
+        else {
+            // Fallback: use the original process.argv (global not available)
+            const args = process.argv.slice(1)
+                .map(a => `'${a.replace(/'/g, "'\\''")}'`)
+                .join(' ');
+            cmd = `sleep 2 && exec ${process.execPath} ${args}`;
+            console.log('[AutoUpdater] No global binary found, restarting from current path');
+        }
         try {
             const child = spawn('sh', ['-c', cmd], {
                 detached: true,

package/dist/core/UpdateChecker.js

@@ -98,8 +98,9 @@ export class UpdateChecker {
             };
         }
         try {
-            // Execute npm update
-            await this.execAsync('npm', ['update', '-g', 'instar'], 120000);
+            // Use `npm install -g instar@latest` — `npm update -g` is unreliable
+            // for global packages and often silently fails to change the version
+            await this.execAsync('npm', ['install', '-g', 'instar@latest'], 120000);
         }
         catch (err) {
             return {

package/dist/core/types.d.ts

@@ -67,6 +67,10 @@ export interface JobDefinition {
     tags?: string[];
     /** Telegram topic ID this job reports to (auto-created if not set) */
     topicId?: number;
+    /** Set to false to disable all Telegram notifications for this job.
+     *  Also prevents topic creation in ensureJobTopics.
+     *  Useful for low-signal jobs that report via other channels. */
+    telegramNotify?: boolean;
     /** Grounding configuration — what context this job needs at session start */
     grounding?: JobGrounding;
     /** LLM supervision tier — see docs/LLM-SUPERVISED-EXECUTION.md */

package/dist/index.d.ts

@@ -28,6 +28,8 @@ export { HealthChecker } from './monitoring/HealthChecker.js';
 export { QuotaTracker } from './monitoring/QuotaTracker.js';
 export type { RemoteQuotaResult } from './monitoring/QuotaTracker.js';
 export { classifySessionDeath } from './monitoring/QuotaExhaustionDetector.js';
+export { AccountSwitcher } from './monitoring/AccountSwitcher.js';
+export { QuotaNotifier } from './monitoring/QuotaNotifier.js';
 export { SleepWakeDetector } from './core/SleepWakeDetector.js';
 export { TelegramAdapter } from './messaging/TelegramAdapter.js';
 export type { TelegramConfig } from './messaging/TelegramAdapter.js';

package/dist/index.js

@@ -29,6 +29,8 @@ export { corsMiddleware, authMiddleware, rateLimiter, requestTimeout, errorHandl
 export { HealthChecker } from './monitoring/HealthChecker.js';
 export { QuotaTracker } from './monitoring/QuotaTracker.js';
 export { classifySessionDeath } from './monitoring/QuotaExhaustionDetector.js';
+export { AccountSwitcher } from './monitoring/AccountSwitcher.js';
+export { QuotaNotifier } from './monitoring/QuotaNotifier.js';
 export { SleepWakeDetector } from './core/SleepWakeDetector.js';
 // Messaging
 export { TelegramAdapter } from './messaging/TelegramAdapter.js';

package/dist/messaging/TelegramAdapter.d.ts

@@ -86,6 +86,13 @@ export declare class TelegramAdapter implements MessagingAdapter {
     onIsSessionAlive: ((tmuxSession: string) => boolean) | null;
     onIsSessionActive: ((tmuxSession: string) => Promise<boolean>) | null;
     onAttentionStatusChange: ((itemId: string, status: string) => Promise<void>) | null;
+    onSwitchAccountRequest: ((target: string, replyTopicId: number) => Promise<void>) | null;
+    onQuotaStatusRequest: ((replyTopicId: number) => Promise<void>) | null;
+    onLoginRequest: ((email: string | null, replyTopicId: number) => Promise<void>) | null;
+    onClassifySessionDeath: ((sessionName: string) => Promise<{
+        cause: string;
+        detail: string;
+    } | null>) | null;
     constructor(config: TelegramConfig, stateDir: string);
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/messaging/TelegramAdapter.js

@@ -70,6 +70,11 @@ export class TelegramAdapter {
     onIsSessionActive = null;
     // Attention queue callbacks
     onAttentionStatusChange = null;
+    // Quota management callbacks
+    onSwitchAccountRequest = null;
+    onQuotaStatusRequest = null;
+    onLoginRequest = null;
+    onClassifySessionDeath = null;
     constructor(config, stateDir) {
         this.config = config;
         this.stateDir = stateDir;
@@ -393,11 +398,31 @@ export class TelegramAdapter {
                 }
             }
             pending.alerted = true;
-            const status = alive ? 'running but not responding' : 'no longer running';
-            const minutesAgo = Math.round((now - pending.injectedAt) / 60000);
-            this.sendToTopic(pending.topicId, `\u26a0\ufe0f No response after ${minutesAgo} minutes. Session "${pending.sessionName}" is ${status}.\n\nMessage: "${pending.messageText}..."${alive ? '\n\nTry /interrupt to unstick, or /restart to respawn.' : '\n\nSend another message to auto-respawn.'}`).catch(err => {
-                console.error(`[telegram] Stall alert failed: ${err}`);
-            });
+            // Classify the stall — check if it's a quota death
+            let isQuotaDeath = false;
+            if (this.onClassifySessionDeath) {
+                try {
+                    const classification = await this.onClassifySessionDeath(pending.sessionName);
+                    if (classification && classification.cause === 'quota_exhaustion') {
+                        isQuotaDeath = true;
+                        this.sendToTopic(pending.topicId, `\ud83d\udd34 Session hit quota limit \u2014 "${pending.sessionName}" can't respond.\n\n` +
+                            `${classification.detail}\n\n` +
+                            `Use /quota to check accounts, /switch-account to switch, or /login to authenticate a new account.`).catch(err => {
+                            console.error(`[telegram] Quota stall alert failed: ${err}`);
+                        });
+                    }
+                }
+                catch {
+                    // Classification failed — fall through to generic
+                }
+            }
+            if (!isQuotaDeath) {
+                const status = alive ? 'running but not responding' : 'no longer running';
+                const minutesAgo = Math.round((now - pending.injectedAt) / 60000);
+                this.sendToTopic(pending.topicId, `\u26a0\ufe0f No response after ${minutesAgo} minutes. Session "${pending.sessionName}" is ${status}.\n\nMessage: "${pending.messageText}..."${alive ? '\n\nTry /interrupt to unstick, or /restart to respawn.' : '\n\nSend another message to auto-respawn.'}`).catch(err => {
+                    console.error(`[telegram] Stall alert failed: ${err}`);
+                });
+            }
         }
         // Clean up old entries (older than 30 minutes, already alerted)
         for (const [key, pending] of this.pendingMessages) {
@@ -683,6 +708,49 @@ export class TelegramAdapter {
             await this.sendToTopic(topicId, lines.join('\n')).catch(() => { });
             return true;
         }
+        // /switch-account (or /sa) <target> — switch active Claude account
+        const switchMatch = text.match(/^\/(?:switch[-_]?account|sa)\s+(.+)$/i);
+        if (switchMatch) {
+            const target = switchMatch[1].trim();
+            if (this.onSwitchAccountRequest) {
+                this.onSwitchAccountRequest(target, topicId).catch(err => {
+                    console.error('[telegram] Switch account failed:', err);
+                    this.sendToTopic(topicId, `Switch failed: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+                });
+            }
+            else {
+                await this.sendToTopic(topicId, 'Account switching not available.').catch(() => { });
+            }
+            return true;
+        }
+        // /quota (or /q) — show multi-account quota summary
+        if (cmd === '/quota' || cmd === '/q') {
+            if (this.onQuotaStatusRequest) {
+                this.onQuotaStatusRequest(topicId).catch(err => {
+                    console.error('[telegram] Quota status failed:', err);
+                    this.sendToTopic(topicId, `Quota check failed: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+                });
+            }
+            else {
+                await this.sendToTopic(topicId, 'Quota status not available.').catch(() => { });
+            }
+            return true;
+        }
+        // /login [email] — seamless OAuth login from Telegram
+        const loginMatch = text.match(/^\/login(?:\s+(.+))?$/i);
+        if (loginMatch) {
+            const email = loginMatch[1]?.trim() || null;
+            if (this.onLoginRequest) {
+                this.onLoginRequest(email, topicId).catch(err => {
+                    console.error('[telegram] Login flow failed:', err);
+                    this.sendToTopic(topicId, `Login failed: ${err instanceof Error ? err.message : String(err)}`).catch(() => { });
+                });
+            }
+            else {
+                await this.sendToTopic(topicId, 'Login not available.').catch(() => { });
+            }
+            return true;
+        }
         return false;
     }
     // ── Message Log ────────────────────────────────────────────

package/dist/monitoring/AccountSwitcher.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Account Switcher — swap active Claude Code account via Keychain manipulation.
+ *
+ * Reads/writes the macOS Keychain entry used by Claude Code for OAuth credentials.
+ * Supports fuzzy matching of account names (e.g., "dawn" matches "dawn@sagemindai.io").
+ *
+ * Ported from Dawn's dawn-server equivalent for general Instar use.
+ */
+export interface SwitchResult {
+    success: boolean;
+    message: string;
+    previousAccount: string | null;
+    newAccount: string | null;
+}
+export declare class AccountSwitcher {
+    private registryPath;
+    private keychainAccount;
+    constructor(registryPath?: string);
+    /**
+     * Switch to a target account. Supports fuzzy matching:
+     * - "dawn" matches "dawn@sagemindai.io"
+     * - Full email also works
+     */
+    switchAccount(target: string): Promise<SwitchResult>;
+    /**
+     * Get status of all accounts.
+     */
+    getAccountStatuses(): Array<{
+        email: string;
+        name: string | null;
+        isActive: boolean;
+        hasToken: boolean;
+        tokenExpired: boolean;
+        isStale: boolean;
+        weeklyPercent: number;
+        fiveHourPercent: number | null;
+    }>;
+    private resolveAccount;
+    private readFromKeychain;
+    private writeToKeychain;
+    private loadRegistry;
+    private saveRegistry;
+}
+//# sourceMappingURL=AccountSwitcher.d.ts.map

package/dist/monitoring/AccountSwitcher.js

@@ -0,0 +1,185 @@
+/**
+ * Account Switcher — swap active Claude Code account via Keychain manipulation.
+ *
+ * Reads/writes the macOS Keychain entry used by Claude Code for OAuth credentials.
+ * Supports fuzzy matching of account names (e.g., "dawn" matches "dawn@sagemindai.io").
+ *
+ * Ported from Dawn's dawn-server equivalent for general Instar use.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+export class AccountSwitcher {
+    registryPath;
+    keychainAccount;
+    constructor(registryPath) {
+        this.registryPath = registryPath || path.join(process.env.HOME || '', '.dawn-server/account-registry.json');
+        // Get the macOS username for Keychain access
+        try {
+            this.keychainAccount = execSync('whoami', { encoding: 'utf-8' }).trim();
+        }
+        catch {
+            this.keychainAccount = 'justin';
+        }
+    }
+    /**
+     * Switch to a target account. Supports fuzzy matching:
+     * - "dawn" matches "dawn@sagemindai.io"
+     * - Full email also works
+     */
+    async switchAccount(target) {
+        const registry = this.loadRegistry();
+        if (!registry) {
+            return { success: false, message: 'Account registry not found', previousAccount: null, newAccount: null };
+        }
+        const resolvedEmail = this.resolveAccount(target, registry);
+        if (!resolvedEmail) {
+            const available = Object.keys(registry.accounts)
+                .map(e => {
+                const a = registry.accounts[e];
+                return `${a.name || 'unknown'} (${e})`;
+            })
+                .join(', ');
+            return {
+                success: false,
+                message: `Unknown account "${target}". Available: ${available}`,
+                previousAccount: registry.activeAccountEmail,
+                newAccount: null,
+            };
+        }
+        const account = registry.accounts[resolvedEmail];
+        if (!account) {
+            return {
+                success: false,
+                message: `Account ${resolvedEmail} not in registry`,
+                previousAccount: registry.activeAccountEmail,
+                newAccount: null,
+            };
+        }
+        if (!account.cachedOAuth?.accessToken) {
+            return {
+                success: false,
+                message: `No cached token for ${resolvedEmail}. Use /login to authenticate.`,
+                previousAccount: registry.activeAccountEmail,
+                newAccount: null,
+            };
+        }
+        if (account.cachedOAuth.expiresAt && account.cachedOAuth.expiresAt < Date.now()) {
+            return {
+                success: false,
+                message: `Token for ${resolvedEmail} expired. Use /login to re-authenticate.`,
+                previousAccount: registry.activeAccountEmail,
+                newAccount: null,
+            };
+        }
+        if (registry.activeAccountEmail === resolvedEmail) {
+            return {
+                success: true,
+                message: `${resolvedEmail} is already the active account.`,
+                previousAccount: resolvedEmail,
+                newAccount: resolvedEmail,
+            };
+        }
+        const previousAccount = registry.activeAccountEmail;
+        try {
+            const currentKeychainData = this.readFromKeychain();
+            const newKeychainData = {
+                ...currentKeychainData,
+                claudeAiOauth: {
+                    ...currentKeychainData.claudeAiOauth,
+                    accessToken: account.cachedOAuth.accessToken,
+                },
+            };
+            this.writeToKeychain(newKeychainData);
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: `Failed to write Keychain: ${err instanceof Error ? err.message : String(err)}`,
+                previousAccount,
+                newAccount: null,
+            };
+        }
+        try {
+            registry.activeAccountEmail = resolvedEmail;
+            registry.lastUpdated = new Date().toISOString();
+            this.saveRegistry(registry);
+        }
+        catch (err) {
+            console.error('[AccountSwitcher] Failed to update registry:', err);
+        }
+        const name = account.name || resolvedEmail;
+        return {
+            success: true,
+            message: `Switched to ${name} (${resolvedEmail}). New sessions will use this account.`,
+            previousAccount,
+            newAccount: resolvedEmail,
+        };
+    }
+    /**
+     * Get status of all accounts.
+     */
+    getAccountStatuses() {
+        const registry = this.loadRegistry();
+        if (!registry)
+            return [];
+        return Object.values(registry.accounts).map(account => {
+            const hasToken = !!account.cachedOAuth?.accessToken;
+            const tokenExpired = hasToken && account.cachedOAuth.expiresAt < Date.now();
+            return {
+                email: account.email,
+                name: account.name,
+                isActive: account.email === registry.activeAccountEmail,
+                hasToken,
+                tokenExpired,
+                isStale: !!account.staleSince,
+                weeklyPercent: account.lastQuotaSnapshot?.percentUsed ?? 0,
+                fiveHourPercent: account.lastQuotaSnapshot?.fiveHourUtilization ?? null,
+            };
+        });
+    }
+    resolveAccount(target, registry) {
+        const lower = target.toLowerCase().trim();
+        if (registry.accounts[lower])
+            return lower;
+        for (const email of Object.keys(registry.accounts)) {
+            if (email.toLowerCase() === lower)
+                return email;
+        }
+        for (const email of Object.keys(registry.accounts)) {
+            const prefix = email.split('@')[0].toLowerCase();
+            if (prefix === lower)
+                return email;
+        }
+        for (const [email, account] of Object.entries(registry.accounts)) {
+            if (account.name && account.name.toLowerCase().includes(lower)) {
+                return email;
+            }
+        }
+        return null;
+    }
+    readFromKeychain() {
+        const result = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -w 2>/dev/null`, { encoding: 'utf-8', timeout: 10000 });
+        return JSON.parse(result.trim());
+    }
+    writeToKeychain(data) {
+        const jsonStr = JSON.stringify(data);
+        const hexStr = Buffer.from(jsonStr).toString('hex');
+        execSync(`security -i <<< 'add-generic-password -U -a "${this.keychainAccount}" -s "${KEYCHAIN_SERVICE}" -X "${hexStr}"'`, { timeout: 10000, shell: '/bin/bash' });
+    }
+    loadRegistry() {
+        try {
+            if (!fs.existsSync(this.registryPath))
+                return null;
+            return JSON.parse(fs.readFileSync(this.registryPath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    saveRegistry(registry) {
+        fs.writeFileSync(this.registryPath, JSON.stringify(registry, null, 2), { mode: 0o600 });
+    }
+}
+//# sourceMappingURL=AccountSwitcher.js.map

package/dist/monitoring/QuotaNotifier.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Quota Notifier — sends alerts when quota thresholds are crossed.
+ *
+ * Handles both weekly and 5-hour rate limit notifications independently.
+ * Deduplicates notifications so the same threshold doesn't spam.
+ * Persists state to survive server restarts.
+ *
+ * Ported from Dawn's dawn-server equivalent for general Instar use.
+ */
+import type { QuotaState } from '../core/types.js';
+type SendFn = (topicId: number, text: string) => Promise<void>;
+export declare class QuotaNotifier {
+    private state;
+    private statePath;
+    private sendToTopic;
+    private alertTopicId;
+    constructor(stateDir: string);
+    /**
+     * Configure the notification target.
+     */
+    configure(sendFn: SendFn, alertTopicId: number | null): void;
+    /**
+     * Check quota state and send notifications if thresholds are crossed.
+     */
+    checkAndNotify(quotaState: QuotaState): Promise<void>;
+    /**
+     * Send an ad-hoc alert (e.g., from session death detection).
+     */
+    sendAlert(message: string): Promise<void>;
+    private checkWeeklyThreshold;
+    private checkFiveHourThreshold;
+    private send;
+    private recordNotification;
+    private loadState;
+    private saveState;
+}
+export {};
+//# sourceMappingURL=QuotaNotifier.d.ts.map

package/dist/monitoring/QuotaNotifier.js

@@ -0,0 +1,137 @@
+/**
+ * Quota Notifier — sends alerts when quota thresholds are crossed.
+ *
+ * Handles both weekly and 5-hour rate limit notifications independently.
+ * Deduplicates notifications so the same threshold doesn't spam.
+ * Persists state to survive server restarts.
+ *
+ * Ported from Dawn's dawn-server equivalent for general Instar use.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const WEEKLY_THRESHOLDS = {
+    warning: 70,
+    critical: 85,
+    limit: 95,
+};
+const FIVE_HOUR_THRESHOLDS = {
+    warning: 80,
+    limit: 95,
+};
+export class QuotaNotifier {
+    state;
+    statePath;
+    sendToTopic = null;
+    alertTopicId = null;
+    constructor(stateDir) {
+        this.statePath = path.join(stateDir, 'quota-notifications.json');
+        this.state = this.loadState();
+    }
+    /**
+     * Configure the notification target.
+     */
+    configure(sendFn, alertTopicId) {
+        this.sendToTopic = sendFn;
+        this.alertTopicId = alertTopicId;
+    }
+    /**
+     * Check quota state and send notifications if thresholds are crossed.
+     */
+    async checkAndNotify(quotaState) {
+        const weeklyPercent = quotaState.usagePercent ?? 0;
+        await this.checkWeeklyThreshold(weeklyPercent);
+        const fiveHourPercent = quotaState.fiveHourPercent ?? null;
+        if (fiveHourPercent !== null) {
+            await this.checkFiveHourThreshold(fiveHourPercent);
+        }
+    }
+    /**
+     * Send an ad-hoc alert (e.g., from session death detection).
+     */
+    async sendAlert(message) {
+        await this.send(message);
+    }
+    async checkWeeklyThreshold(percent) {
+        let currentLevel = null;
+        if (percent >= WEEKLY_THRESHOLDS.limit)
+            currentLevel = 'limit';
+        else if (percent >= WEEKLY_THRESHOLDS.critical)
+            currentLevel = 'critical';
+        else if (percent >= WEEKLY_THRESHOLDS.warning)
+            currentLevel = 'warning';
+        if (currentLevel && currentLevel !== this.state.lastWeeklyLevel) {
+            const labels = { warning: 'WARNING', critical: 'CRITICAL', limit: 'LIMIT REACHED' };
+            await this.send(`[QUOTA ${labels[currentLevel]}] Weekly at ${percent}%`);
+            this.state.lastWeeklyLevel = currentLevel;
+            this.recordNotification('weekly', currentLevel, percent);
+            this.saveState();
+        }
+        if (percent < WEEKLY_THRESHOLDS.warning && this.state.lastWeeklyLevel) {
+            this.state.lastWeeklyLevel = null;
+            this.saveState();
+        }
+    }
+    async checkFiveHourThreshold(percent) {
+        let currentLevel = null;
+        if (percent >= FIVE_HOUR_THRESHOLDS.limit)
+            currentLevel = 'limit';
+        else if (percent >= FIVE_HOUR_THRESHOLDS.warning)
+            currentLevel = 'warning';
+        if (currentLevel && currentLevel !== this.state.lastFiveHourLevel) {
+            const labels = { warning: 'WARNING', limit: 'FULL' };
+            await this.send(`[5-HOUR RATE LIMIT ${labels[currentLevel]}] At ${percent}%. Sessions may fail.`);
+            this.state.lastFiveHourLevel = currentLevel;
+            this.recordNotification('five_hour', currentLevel, percent);
+            this.saveState();
+        }
+        if (percent < FIVE_HOUR_THRESHOLDS.warning && this.state.lastFiveHourLevel) {
+            this.state.lastFiveHourLevel = null;
+            this.saveState();
+        }
+    }
+    async send(text) {
+        if (!this.sendToTopic || !this.alertTopicId) {
+            console.log(`[QuotaNotifier] ${text}`);
+            return;
+        }
+        try {
+            await this.sendToTopic(this.alertTopicId, text);
+        }
+        catch (err) {
+            console.error('[QuotaNotifier] Failed to send:', err);
+        }
+    }
+    recordNotification(type, level, percent) {
+        this.state.notifications.push({
+            type,
+            level,
+            percentUsed: percent,
+            timestamp: new Date().toISOString(),
+        });
+        if (this.state.notifications.length > 100) {
+            this.state.notifications = this.state.notifications.slice(-100);
+        }
+        this.state.lastNotifiedAt = new Date().toISOString();
+    }
+    loadState() {
+        try {
+            if (fs.existsSync(this.statePath)) {
+                return JSON.parse(fs.readFileSync(this.statePath, 'utf-8'));
+            }
+        }
+        catch { /* fresh state */ }
+        return { lastWeeklyLevel: null, lastFiveHourLevel: null, notifications: [], lastNotifiedAt: null };
+    }
+    saveState() {
+        try {
+            const dir = path.dirname(this.statePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(this.statePath, JSON.stringify(this.state, null, 2));
+        }
+        catch (err) {
+            console.error('[QuotaNotifier] Failed to save state:', err);
+        }
+    }
+}
+//# sourceMappingURL=QuotaNotifier.js.map

package/dist/scheduler/JobScheduler.js

@@ -362,9 +362,11 @@ export class JobScheduler {
         }
         // Try to drain the queue now that a slot is available
         this.processQueue();
-        // Skip notifications if no messaging configured
+        // Skip notifications if no messaging configured or job opted out
         if (!this.messenger && !this.telegram)
             return;
+        if (job.telegramNotify === false)
+            return;
         // Capture the last output from the tmux session
         let output = '';
         try {
@@ -415,9 +417,10 @@ export class JobScheduler {
         else {
             summary += '\n_No output captured (session already closed)_';
         }
-        // Skip Telegram notification for successful jobs with no meaningful output
-        // Prevents empty notification spam (e.g., dispatch-check when dispatch is unconfigured)
-        if (!failed && (!output || !output.trim())) {
+        // Skip Telegram notification for jobs with no meaningful output — applies regardless of status.
+        // Failure alerts are already handled by alertOnConsecutiveFailures above.
+        // Prevents "No output captured (session already closed)" spam on every failed cycle.
+        if (!output || !output.trim()) {
             console.log(`[scheduler] Skipping notification for ${job.slug} — no meaningful output`);
             return;
         }
@@ -463,6 +466,9 @@ export class JobScheduler {
         // Load existing topic mappings
         const mappings = this.state.get('job-topic-mappings') ?? {};
         for (const job of enabledJobs) {
+            // Opt-out: skip topic creation entirely when telegramNotify is explicitly false
+            if (job.telegramNotify === false)
+                continue;
             // If job already has a topicId (from jobs.json or previous mapping), use it
             if (job.topicId) {
                 mappings[job.slug] = job.topicId;

package/package.json

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