instar 0.6.15 → 0.7.0

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

@@ -24,43 +24,68 @@ This wizard runs in a terminal that may be narrow (80-120 chars). Long text gets
 **Good** (fits in terminal):
 > Everything here is just a starting point. You can change any of it later — or just tell your agent to adjust itself.
 
-## Phase 1: Welcome & Use Case Selection
+## Phase 1: Context Detection & Welcome
 
-Start with a brief welcome, then immediately ask HOW they want to use Instar.
+**Do NOT ask "how do you want to use Instar?"** Instead, detect the context automatically and present an intelligent default.
+
+### Step 1a: Detect Environment
+
+Run these checks BEFORE showing anything to the user:
+
+```bash
+# Check if we're inside a git repository
+git rev-parse --show-toplevel 2>/dev/null
+
+# Get the repo name if it exists
+basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null
+
+# Check for common project indicators
+ls package.json Cargo.toml pyproject.toml go.mod Gemfile pom.xml 2>/dev/null
+```
+
+### Step 1b: Present Context-Aware Welcome
+
+**If inside a git repository:**
 
 ---
 
 **Welcome to Instar!**
 
-Instar turns Claude Code into a persistent agent you just talk to — through Telegram, not the terminal. This setup gets you there. Two ways to use it:
+I see you're in **[repo-name]** — I'll set up a persistent agent for this project.
+
+Your agent will monitor, build, and maintain this codebase. You'll talk to it through Telegram — no terminal needed after setup.
+
+---
+
+Then proceed directly — no "project vs general" question needed. The context made it obvious.
+
+If the user objects ("actually I want a personal agent, not a project agent"), accommodate immediately: "Got it — setting up a personal agent instead."
+
+**If NOT inside a git repository:**
 
 ---
 
-Present a question with two clear options:
+**Welcome to Instar!**
+
+You're not inside a project, so I'll set up a personal agent — a persistent AI companion you talk to through Telegram.
+
+It can research, schedule tasks, manage files, and grow over time.
+
+---
 
-1. **Project Agent** — Add an agent to an existing codebase. It monitors, builds, and maintains your project.
-2. **General Agent** — A personal agent on your computer. Like having a persistent AI assistant you talk to through Telegram.
+Then ask: "What should your agent be called?" (default: "my-agent")
 
-This choice determines the defaults, but the agent can always grow into more.
+### Key principle: Telegram is the interface, always
 
-### If "Project Agent" selected:
-- Use the current working directory as the project
-- Default jobs focus on health checks, code monitoring, reflection
-- The agent's identity centers on the project
+Regardless of project or personal agent, **Telegram is how you talk to your agent**. This should be clear from the very first message. Don't present it as an optional add-on — it's the destination of this entire setup.
 
-### If "General Agent" selected:
-- Ask for a name for the agent (this becomes the directory name)
-- Create the directory in the current location or home dir
-- Default jobs focus on communication, scheduling, research
-- **Telegram is essential** — without it, a general agent has no natural interface
-- Frame the identity around being a personal assistant, not a code monitor
-- The AGENT.md should emphasize: "I'm your personal agent. Talk to me through Telegram."
+The terminal session is the on-ramp. Telegram is where the agent experience lives.
 
 ## Phase 2: Identity Bootstrap — The Birth Conversation
 
 **This is the most important part.** Have a conversation to understand who the user is and who their agent will become. Keep it natural and concise.
 
-For **General Agents**: emphasize that this agent will be their persistent companion. It grows, learns, and communicates through Telegram. It's not a project tool — it's a presence.
+For **Personal Agents**: emphasize that this agent will be their persistent companion. It grows, learns, and communicates through Telegram. It's not a project tool — it's a presence.
 
 For **Project Agents**: emphasize that this agent will own the project's health and development. It monitors, builds, and maintains.
 
@@ -225,30 +250,11 @@ This project uses instar for persistent agent capabilities.
 - **Research before escalating** — Check tools first. Build solutions. "Needs human" is last resort.
 ```
 
-## Phase 3: Technical Configuration
-
-Now that identity is established, move to the technical setup. This feels more natural — the user already knows what they're building and why.
-
-### 3a. Project Detection
-
-- The project directory is passed in the prompt (e.g., "The project to set up is at: /path/to/project")
-- All files should be written there, not in the instar package directory
-- Check if `.instar/config.json` already exists (offer to reconfigure or skip)
-- Verify prerequisites: check that `tmux` and `claude` CLI are available
-
-```bash
-which tmux
-which claude
-```
-
-### 3b. Server Configuration
+## Phase 3: Telegram Setup — The Destination
 
-- **Port** (default: 4040) — "The agent runs a small HTTP server for health checks and internal communication."
-- **Max sessions** (default: 3) — "This limits how many Claude sessions can run at once. 2-3 is usually right."
+**Telegram comes BEFORE technical configuration.** It's the whole point — everything else supports getting the user onto Telegram.
 
-### 3c. Telegram Setup — The Destination
-
-**This terminal session is the on-ramp. Telegram is where the agent experience truly begins.** Frame it that way:
+Frame it clearly:
 
 > Right now we're in a terminal. Telegram is where your agent comes alive:
 > - **Just talk** — no commands, no terminal, just conversation
@@ -256,9 +262,7 @@ which claude
 > - **Mobile access** — your agent is always reachable
 > - **Proactive** — your agent reaches out when something matters
 
-The goal of this setup is to get the user onto Telegram as fast as possible. Everything else (jobs, config, technical setup) supports that destination.
-
-For **General Agents**: Telegram is essential. Without it, there IS no natural interface. Be direct: "This is how you'll talk to your agent."
+For **Personal Agents**: Telegram is essential. Without it, there IS no natural interface. Be direct: "This is how you'll talk to your agent."
 
 For **Project Agents**: Telegram is strongly recommended. Frame it as: "Your agent can message you about builds, issues, and progress — you just reply."
 
@@ -382,7 +386,32 @@ curl -s "https://api.telegram.org/bot${TOKEN}/getUpdates?timeout=5"
    - Look for `chat.id` where `chat.type` is "supergroup" or "group"
    - If auto-detection fails, guide manual entry
 
-### 3d. Job Scheduler (Optional)
+## Phase 4: Technical Configuration
+
+Now that identity and Telegram are established, handle the remaining technical setup. These should feel like sensible defaults, not interrogation.
+
+### 4a. Project Detection
+
+- The project directory is passed in the prompt (e.g., "The project to set up is at: /path/to/project")
+- All files should be written there, not in the instar package directory
+- Check if `.instar/config.json` already exists (offer to reconfigure or skip)
+- Verify prerequisites: check that `tmux` and `claude` CLI are available
+
+```bash
+which tmux
+which claude
+```
+
+### 4b. Server Configuration
+
+Present sensible defaults — don't make the user think about these unless they want to:
+
+- **Port** (default: 4040) — "The agent runs a small local server."
+- **Max sessions** (default: 3) — "How many Claude sessions can run at once."
+
+Ask as a single confirmation: "I'll use port 4040 with up to 3 sessions. Want to change these?" If yes, ask for specifics. If no, move on.
+
+### 4c. Job Scheduler (Optional)
 
 - Ask if they want scheduled jobs
 - If yes, walk through adding a first job:
@@ -393,7 +422,7 @@ curl -s "https://api.telegram.org/bot${TOKEN}/getUpdates?timeout=5"
   - **Execution type**: prompt (AI instruction), script (shell script), or skill (slash command)
 - Offer to add more jobs
 
-### 3e. Write Configuration Files
+### 4d. Write Configuration Files
 
 Create the directory structure and write config files:
 
@@ -438,7 +467,7 @@ mkdir -p .instar/state/sessions .instar/state/jobs .instar/logs
 
 **`.instar/users.json`**: Array of user objects from the identity conversation.
 
-### 3f. Update .gitignore
+### 4e. Update .gitignore
 
 Append if not present:
 ```
@@ -447,7 +476,7 @@ Append if not present:
 .instar/logs/
 ```
 
-## Phase 4: Summary & Launch
+## Phase 5: Summary & Launch
 
 Show what was created briefly, then get the user to their agent.
 
@@ -485,4 +514,4 @@ Offer to start the server.
 
 ## Starting
 
-Begin by reading the project directory, checking for existing config, and then launching into the welcome explanation followed by the identity conversation. Let the conversation flow naturally.
+Begin by detecting the environment (git repo check, project file check), then present the context-aware welcome. Let the conversation flow naturally from there.

package/dist/commands/server.js

@@ -28,6 +28,7 @@ import { TelegraphService } from '../publishing/TelegraphService.js';
 import { PrivateViewer } from '../publishing/PrivateViewer.js';
 import { TunnelManager } from '../tunnel/TunnelManager.js';
 import { EvolutionManager } from '../core/EvolutionManager.js';
+import { QuotaTracker } from '../monitoring/QuotaTracker.js';
 /**
  * Respawn a session for a topic, including thread history in the bootstrap.
  * This prevents "thread drift" where respawned sessions lose context.
@@ -381,9 +382,24 @@ export async function startServer(options) {
             const count = relationships.getAll().length;
             console.log(pc.green(`  Relationships loaded: ${count} tracked (${intelligenceMode})`));
         }
+        // Set up quota tracking if enabled
+        let quotaTracker;
+        if (config.monitoring?.quotaTracking) {
+            const quotaFile = config.monitoring.quotaStateFile
+                || path.join(config.stateDir, 'quota-state.json');
+            quotaTracker = new QuotaTracker({
+                quotaFile,
+                thresholds: config.scheduler?.quotaThresholds ?? { normal: 50, elevated: 60, critical: 80, shutdown: 95 },
+            });
+            console.log(pc.green(`  Quota tracking enabled (${quotaFile})`));
+        }
         let scheduler;
         if (config.scheduler.enabled) {
             scheduler = new JobScheduler(config.scheduler, sessionManager, state, config.stateDir);
+            if (quotaTracker) {
+                scheduler.canRunJob = quotaTracker.canRunJob.bind(quotaTracker);
+                scheduler.setQuotaTracker(quotaTracker);
+            }
             scheduler.start();
             console.log(pc.green('  Scheduler started'));
         }
@@ -487,7 +503,7 @@ export async function startServer(options) {
             ...(config.evolution || {}),
         });
         console.log(pc.green('  Evolution system enabled'));
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, publisher, viewer, tunnel, evolution });
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, quotaTracker, publisher, viewer, tunnel, evolution });
         await server.start();
         // Start tunnel AFTER server is listening
         if (tunnel) {

package/dist/commands/setup.js

@@ -69,8 +69,23 @@ export async function runSetup(opts) {
     console.log(pc.dim('  Security is enforced through behavioral hooks, identity grounding, and'));
     console.log(pc.dim('  scoped access — not permission dialogs. See: README.md > Security Model'));
     console.log();
+    // Detect git context to pass to the conversational wizard
+    const projectDir = process.cwd();
+    let gitContext = '';
+    try {
+        const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const repoName = path.basename(gitRoot);
+        gitContext = ` This directory is inside a git repository "${repoName}" at ${gitRoot}.`;
+    }
+    catch {
+        gitContext = ' This directory is NOT inside a git repository.';
+    }
     // Launch Claude Code from the instar package root (where .claude/skills/ lives)
-    // and pass the target project directory in the prompt.
+    // and pass the target project directory + git context in the prompt.
     //
     // --dangerously-skip-permissions is required here because the setup wizard
     // runs in instar's OWN package directory (instarRoot), not the user's
@@ -78,10 +93,9 @@ export async function runSetup(opts) {
     // user's project directory, which breaks the interactive flow. The wizard
     // only writes to well-defined locations (.instar/, .claude/, CLAUDE.md).
     const instarRoot = findInstarRoot();
-    const projectDir = process.cwd();
     const child = spawn(claudePath, [
         '--dangerously-skip-permissions',
-        `/setup-wizard The project to set up is at: ${projectDir}`,
+        `/setup-wizard The project to set up is at: ${projectDir}.${gitContext}`,
     ], {
         cwd: instarRoot,
         stdio: 'inherit',
@@ -126,6 +140,22 @@ function findInstarRoot() {
     // Fallback: assume we're in dist/commands/ — go up to root
     return path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
 }
+/**
+ * Detect whether the current directory is inside a git repository.
+ */
+function detectGitRepo(dir) {
+    try {
+        const root = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: dir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return { isRepo: true, repoRoot: root, repoName: path.basename(root) };
+    }
+    catch {
+        return { isRepo: false };
+    }
+}
 /**
  * Classic inquirer-based setup wizard.
  * The original interactive setup experience.
@@ -133,7 +163,7 @@ function findInstarRoot() {
 async function runClassicSetup() {
     console.log();
     console.log(pc.bold('  Welcome to Instar'));
-    console.log(pc.dim('  Persistent agent infrastructure for any Claude Code project'));
+    console.log(pc.dim('  Turn Claude Code into a persistent agent you talk to through Telegram.'));
     console.log();
     // ── Step 0: Check and install prerequisites ─────────────────────
     const prereqs = await ensurePrerequisites();
@@ -143,19 +173,59 @@ async function runClassicSetup() {
     const tmuxPath = prereqs.results.find(r => r.name === 'tmux').path;
     // Use a scoped name to avoid shadowing the outer runSetup's claudePath
     const claudePath = prereqs.results.find(r => r.name === 'Claude CLI').path;
-    // ── Step 1: Project ──────────────────────────────────────────────
+    // ── Step 1: Detect context and determine mode ─────────────────
     const detectedDir = process.cwd();
-    const detectedName = path.basename(detectedDir);
-    const projectDir = detectedDir; // Always use cwd
-    const projectName = await input({
-        message: 'Project name',
-        default: detectedName,
-    });
+    const gitInfo = detectGitRepo(detectedDir);
+    let projectDir;
+    let projectName;
+    let isProjectAgent;
+    if (gitInfo.isRepo) {
+        // Inside a git repository — suggest project agent
+        console.log(`  ${pc.green('✓')} Detected git repository: ${pc.cyan(gitInfo.repoName)}`);
+        console.log(pc.dim(`    ${gitInfo.repoRoot}`));
+        console.log();
+        console.log(pc.dim('  Your agent will live alongside this project — monitoring, building,'));
+        console.log(pc.dim('  and maintaining it. You talk to it through Telegram.'));
+        console.log();
+        const useThisRepo = await confirm({
+            message: `Set up an agent for ${gitInfo.repoName}?`,
+            default: true,
+        });
+        if (useThisRepo) {
+            projectDir = gitInfo.repoRoot;
+            projectName = await input({
+                message: 'Agent name',
+                default: gitInfo.repoName,
+            });
+            isProjectAgent = true;
+        }
+        else {
+            // They want a general agent instead
+            projectName = await input({
+                message: 'What should your agent be called?',
+                default: 'my-agent',
+            });
+            projectDir = detectedDir;
+            isProjectAgent = false;
+        }
+    }
+    else {
+        // Not in a git repo — this is a general/personal agent
+        console.log(pc.dim('  No git repository detected — setting up a personal agent.'));
+        console.log(pc.dim('  A personal agent lives on your machine and you talk to it through Telegram.'));
+        console.log();
+        projectName = await input({
+            message: 'What should your agent be called?',
+            default: 'my-agent',
+        });
+        projectDir = detectedDir;
+        isProjectAgent = false;
+    }
     // Check if already initialized
     const stateDir = path.join(projectDir, '.instar');
     if (fs.existsSync(path.join(stateDir, 'config.json'))) {
         const overwrite = await confirm({
-            message: 'Agent kit already initialized here. Reconfigure?',
+            message: 'Agent already initialized here. Reconfigure?',
             default: false,
         });
         if (!overwrite) {
@@ -163,7 +233,19 @@ async function runClassicSetup() {
             return;
         }
     }
-    // ── Step 2: Server port + sessions ─────────────────────────────
+    // ── Step 2: Telegram — the primary interface ───────────────────
+    console.log();
+    console.log(pc.bold('  Telegram — How You Talk to Your Agent'));
+    console.log();
+    console.log(pc.dim('  Once connected, you just talk — no commands, no terminal.'));
+    console.log(pc.dim('  Topic threads, message history, mobile access, proactive notifications.'));
+    if (!isProjectAgent) {
+        console.log();
+        console.log(pc.dim('  For a personal agent, Telegram IS the interface.'));
+    }
+    console.log();
+    const telegramConfig = await promptForTelegram();
+    // ── Step 3: Server config (sensible defaults) ──────────────────
     const port = await number({
         message: 'Server port',
         default: 4040,
@@ -182,14 +264,6 @@ async function runClassicSetup() {
             return true;
         },
     }) ?? 3;
-    // ── Step 3: Telegram (BEFORE users, so we know context) ────────
-    console.log();
-    console.log(pc.bold('  Telegram — Where Your Agent Lives'));
-    console.log(pc.dim('  Telegram is where the real experience begins.'));
-    console.log(pc.dim('  Once connected, you just talk — no commands, no terminal.'));
-    console.log(pc.dim('  Topic threads, message history, mobile access, proactive notifications.'));
-    console.log();
-    const telegramConfig = await promptForTelegram();
     // ── Step 4: User setup ─────────────────────────────────────────
     console.log();
     const addUser = await confirm({

package/dist/core/types.d.ts

@@ -197,8 +197,10 @@ export interface MessagingAdapter {
     resolveUser(channelIdentifier: string): Promise<string | null>;
 }
 export interface QuotaState {
-    /** Current usage percentage (0-100) */
+    /** Current weekly usage percentage (0-100) */
     usagePercent: number;
+    /** 5-hour rolling rate limit utilization (0-100), if available */
+    fiveHourPercent?: number;
     /** When usage data was last updated */
     lastUpdated: string;
     /** Per-account breakdown if multi-account */
@@ -209,9 +211,18 @@ export interface QuotaState {
 export interface AccountQuota {
     email: string;
     usagePercent: number;
+    /** 5-hour rolling rate limit utilization for this account */
+    fiveHourPercent?: number;
     isActive: boolean;
     lastUpdated: string;
 }
+/** Cause of a session's death, as classified by QuotaExhaustionDetector */
+export type SessionDeathCause = 'quota_exhaustion' | 'context_exhausted' | 'crash' | 'timeout' | 'normal_exit' | 'unknown';
+export interface SessionDeathClassification {
+    cause: SessionDeathCause;
+    confidence: 'high' | 'medium' | 'low';
+    detail: string;
+}
 export interface HealthStatus {
     status: 'healthy' | 'degraded' | 'unhealthy';
     components: Record<string, ComponentHealth>;

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export type { RouteContext } from './server/routes.js';
 export { corsMiddleware, authMiddleware, rateLimiter, requestTimeout, errorHandler } from './server/middleware.js';
 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 { SleepWakeDetector } from './core/SleepWakeDetector.js';
 export { TelegramAdapter } from './messaging/TelegramAdapter.js';
 export type { TelegramConfig } from './messaging/TelegramAdapter.js';
@@ -35,6 +37,6 @@ export { PrivateViewer } from './publishing/PrivateViewer.js';
 export type { PrivateView, PrivateViewerConfig } from './publishing/PrivateViewer.js';
 export { TunnelManager } from './tunnel/TunnelManager.js';
 export type { TunnelConfig, TunnelState } from './tunnel/TunnelManager.js';
-export type { Session, SessionStatus, SessionManagerConfig, ModelTier, JobDefinition, JobPriority, JobExecution, JobState, JobSchedulerConfig, UserProfile, UserChannel, UserPreferences, Message, OutgoingMessage, MessagingAdapter, MessagingAdapterConfig, QuotaState, AccountQuota, HealthStatus, ComponentHealth, ActivityEvent, InstarConfig, MonitoringConfig, RelationshipRecord, RelationshipManagerConfig, InteractionSummary, FeedbackItem, FeedbackConfig, UpdateInfo, UpdateResult, DispatchConfig, UpdateConfig, PublishingConfig, TunnelConfigType, SkipReason, SkipEvent, WorkloadSignal, AutoTuneState, IntelligenceProvider, IntelligenceOptions, EvolutionProposal, EvolutionType, EvolutionStatus, LearningEntry, LearningSource, CapabilityGap, GapCategory, ActionItem, EvolutionManagerConfig, } from './core/types.js';
+export type { Session, SessionStatus, SessionManagerConfig, ModelTier, JobDefinition, JobPriority, JobExecution, JobState, JobSchedulerConfig, UserProfile, UserChannel, UserPreferences, Message, OutgoingMessage, MessagingAdapter, MessagingAdapterConfig, QuotaState, AccountQuota, SessionDeathCause, SessionDeathClassification, HealthStatus, ComponentHealth, ActivityEvent, InstarConfig, MonitoringConfig, RelationshipRecord, RelationshipManagerConfig, InteractionSummary, FeedbackItem, FeedbackConfig, UpdateInfo, UpdateResult, DispatchConfig, UpdateConfig, PublishingConfig, TunnelConfigType, SkipReason, SkipEvent, WorkloadSignal, AutoTuneState, IntelligenceProvider, IntelligenceOptions, EvolutionProposal, EvolutionType, EvolutionStatus, LearningEntry, LearningSource, CapabilityGap, GapCategory, ActionItem, EvolutionManagerConfig, } from './core/types.js';
 export type { Dispatch, DispatchCheckResult, DispatchEvaluation, EvaluationDecision, DispatchFeedback, DispatchStats } from './core/DispatchManager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

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

package/dist/monitoring/QuotaExhaustionDetector.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Quota Exhaustion Detector — classifies WHY a session died.
+ *
+ * Pattern-matches tmux output from a dead session against known
+ * failure signatures, cross-references with quota state to produce
+ * a confidence-weighted classification.
+ *
+ * Use cases:
+ * - Skip ledger: record quota_exhaustion vs crash vs normal_exit
+ * - Telegram alerts: "session died because quota exhausted"
+ * - Auto-recovery: trigger account switch on repeated quota deaths
+ *
+ * Ported from Dawn's dawn-server/src/quota/QuotaExhaustionDetector.ts,
+ * simplified for general Instar use (no Telegram dependency).
+ */
+import type { QuotaState, SessionDeathClassification } from '../core/types.js';
+/**
+ * Classify why a session died based on its terminal output and quota state.
+ */
+export declare function classifySessionDeath(tmuxOutput: string, quotaState?: QuotaState | null): SessionDeathClassification;
+//# sourceMappingURL=QuotaExhaustionDetector.d.ts.map

package/dist/monitoring/QuotaExhaustionDetector.js

@@ -0,0 +1,136 @@
+/**
+ * Quota Exhaustion Detector — classifies WHY a session died.
+ *
+ * Pattern-matches tmux output from a dead session against known
+ * failure signatures, cross-references with quota state to produce
+ * a confidence-weighted classification.
+ *
+ * Use cases:
+ * - Skip ledger: record quota_exhaustion vs crash vs normal_exit
+ * - Telegram alerts: "session died because quota exhausted"
+ * - Auto-recovery: trigger account switch on repeated quota deaths
+ *
+ * Ported from Dawn's dawn-server/src/quota/QuotaExhaustionDetector.ts,
+ * simplified for general Instar use (no Telegram dependency).
+ */
+// Pattern groups for classification
+const QUOTA_PATTERNS = [
+    'overloaded_error',
+    'rate_limit',
+    '429',
+    'quota.*exceeded',
+    'usage.*limit',
+    'too many requests',
+    'resource_exhausted',
+    'capacity',
+    'throttl',
+    'rate limit exceeded',
+];
+const CONTEXT_PATTERNS = [
+    'context.*exhaust',
+    'context.*limit',
+    'context.*full',
+    'token.*limit.*reached',
+    'maximum.*context',
+    'conversation is too long',
+];
+const CRASH_PATTERNS = [
+    'SIGABRT',
+    'SIGSEGV',
+    'SIGKILL',
+    'fatal error',
+    'unhandled.*exception',
+    'panic:',
+    'stack overflow',
+    'out of memory',
+    'heap.*out',
+];
+const NORMAL_EXIT_PATTERNS = [
+    'Session ended',
+    'Goodbye!',
+    'has been completed',
+    'Auto-exit',
+    '✓',
+    'exited cleanly',
+];
+/**
+ * Classify why a session died based on its terminal output and quota state.
+ */
+export function classifySessionDeath(tmuxOutput, quotaState) {
+    if (!tmuxOutput || tmuxOutput.trim().length === 0) {
+        return { cause: 'unknown', confidence: 'low', detail: 'No output captured' };
+    }
+    const output = tmuxOutput.toLowerCase();
+    // Check each pattern group
+    const quotaMatch = matchPatterns(output, QUOTA_PATTERNS);
+    const contextMatch = matchPatterns(output, CONTEXT_PATTERNS);
+    const crashMatch = matchPatterns(output, CRASH_PATTERNS);
+    const normalMatch = matchPatterns(output, NORMAL_EXIT_PATTERNS);
+    // Normal exit takes precedence if present
+    if (normalMatch && !quotaMatch && !crashMatch) {
+        return {
+            cause: 'normal_exit',
+            confidence: 'high',
+            detail: `Matched normal exit pattern: "${normalMatch}"`,
+        };
+    }
+    // Quota exhaustion — cross-reference with state for confidence
+    if (quotaMatch) {
+        let confidence = 'medium';
+        // Cross-reference: if 5-hour is high, boost confidence
+        if (quotaState) {
+            const fiveHour = quotaState.fiveHourPercent;
+            const weekly = quotaState.usagePercent;
+            if (typeof fiveHour === 'number' && fiveHour > 90) {
+                confidence = 'high';
+            }
+            else if (weekly > 85) {
+                confidence = 'high';
+            }
+        }
+        return {
+            cause: 'quota_exhaustion',
+            confidence,
+            detail: `Matched quota pattern: "${quotaMatch}"` +
+                (quotaState ? ` (weekly: ${quotaState.usagePercent}%, 5h: ${quotaState.fiveHourPercent ?? 'n/a'}%)` : ''),
+        };
+    }
+    // Context exhaustion
+    if (contextMatch) {
+        return {
+            cause: 'context_exhausted',
+            confidence: 'medium',
+            detail: `Matched context pattern: "${contextMatch}"`,
+        };
+    }
+    // Crash
+    if (crashMatch) {
+        return {
+            cause: 'crash',
+            confidence: 'medium',
+            detail: `Matched crash pattern: "${crashMatch}"`,
+        };
+    }
+    return { cause: 'unknown', confidence: 'low', detail: 'No patterns matched' };
+}
+/**
+ * Check if output matches any pattern in a group.
+ * Returns the first matching pattern string, or null.
+ */
+function matchPatterns(output, patterns) {
+    for (const pattern of patterns) {
+        try {
+            if (new RegExp(pattern, 'i').test(output)) {
+                return pattern;
+            }
+        }
+        catch {
+            // If regex is invalid, try simple string match
+            if (output.includes(pattern.toLowerCase())) {
+                return pattern;
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=QuotaExhaustionDetector.js.map

package/dist/monitoring/QuotaTracker.d.ts

@@ -34,16 +34,28 @@ export declare class QuotaTracker {
     /**
      * Determine if a job at the given priority should run based on current quota.
      *
-     * Threshold logic:
-     * - Below normal (e.g. 50%): all jobs run
-     * - Above normal but below elevated (e.g. 60%): high+ only
-     * - Above elevated but below critical (e.g. 80%): critical only
-     * - Above critical (e.g. 95%): no jobs
+     * Checks BOTH weekly usage AND 5-hour rate limit:
+     * - 5-hour >= 95%: block ALL spawns (sessions will immediately fail)
+     * - 5-hour >= 80%: only critical priority
+     * - Weekly >= shutdown (e.g. 95%): no jobs
+     * - Weekly >= critical (e.g. 80%): critical only
+     * - Weekly >= elevated (e.g. 60%): high+ only
+     * - Weekly >= normal (e.g. 50%): medium+ only
      *
      * If quota data is unavailable or stale, defaults to allowing all jobs
      * (fail-open — better to run than to silently stop).
      */
     canRunJob(priority: JobPriority): boolean;
+    /**
+     * Check if a session should be spawned at the given priority.
+     * Returns a structured result with reason — useful for logging and notifications.
+     *
+     * Checks both weekly AND 5-hour rate limits.
+     */
+    shouldSpawnSession(priority?: JobPriority): {
+        allowed: boolean;
+        reason: string;
+    };
     /**
      * Write a quota state to the file (for collector scripts or manual updates).
      */
@@ -52,5 +64,29 @@ export declare class QuotaTracker {
      * Get the recommendation string for display purposes.
      */
     getRecommendation(): QuotaState['recommendation'];
+    /**
+     * Fetch quota status from a remote API (e.g., Dawn's /api/instar/quota).
+     * If the remote says canProceed=false, updates local state accordingly.
+     *
+     * This allows Instar agents to check a central quota authority before
+     * spawning sessions, preventing wasted attempts on exhausted machines.
+     *
+     * @param url - Full URL to the quota API (e.g., "https://dawn.bot-me.ai/api/instar/quota")
+     * @param apiKey - Authorization token (sent as Bearer header)
+     * @param timeoutMs - Request timeout (default 5000ms)
+     * @returns Remote quota status, or null on failure (fail-open)
+     */
+    fetchRemoteQuota(url: string, apiKey: string, timeoutMs?: number): Promise<RemoteQuotaResult | null>;
+}
+/** Result from a remote quota API (e.g., /api/instar/quota) */
+export interface RemoteQuotaResult {
+    canProceed: boolean;
+    blockReason?: string | null;
+    activeAccount?: string | null;
+    weeklyPercent: number;
+    fiveHourPercent?: number | null;
+    canRunPriority?: string;
+    recommendation?: string | null;
+    stale?: boolean;
 }
 //# sourceMappingURL=QuotaTracker.d.ts.map

package/dist/monitoring/QuotaTracker.js

@@ -60,36 +60,70 @@ export class QuotaTracker {
     /**
      * Determine if a job at the given priority should run based on current quota.
      *
-     * Threshold logic:
-     * - Below normal (e.g. 50%): all jobs run
-     * - Above normal but below elevated (e.g. 60%): high+ only
-     * - Above elevated but below critical (e.g. 80%): critical only
-     * - Above critical (e.g. 95%): no jobs
+     * Checks BOTH weekly usage AND 5-hour rate limit:
+     * - 5-hour >= 95%: block ALL spawns (sessions will immediately fail)
+     * - 5-hour >= 80%: only critical priority
+     * - Weekly >= shutdown (e.g. 95%): no jobs
+     * - Weekly >= critical (e.g. 80%): critical only
+     * - Weekly >= elevated (e.g. 60%): high+ only
+     * - Weekly >= normal (e.g. 50%): medium+ only
      *
      * If quota data is unavailable or stale, defaults to allowing all jobs
      * (fail-open — better to run than to silently stop).
      */
     canRunJob(priority) {
+        const result = this.shouldSpawnSession(priority);
+        return result.allowed;
+    }
+    /**
+     * Check if a session should be spawned at the given priority.
+     * Returns a structured result with reason — useful for logging and notifications.
+     *
+     * Checks both weekly AND 5-hour rate limits.
+     */
+    shouldSpawnSession(priority) {
         const state = this.getState();
         if (!state)
-            return true; // No data → fail open
+            return { allowed: true, reason: 'No quota data — fail open' };
+        // Check 5-hour rate limit first — these cause immediate session failures
+        const fiveHour = state.fiveHourPercent;
+        if (typeof fiveHour === 'number' && isFinite(fiveHour)) {
+            if (fiveHour >= 95) {
+                return { allowed: false, reason: `5-hour rate limit at ${fiveHour}% — sessions will fail immediately` };
+            }
+            if (fiveHour >= 80 && priority && priority !== 'critical') {
+                return { allowed: false, reason: `5-hour rate limit at ${fiveHour}% — only critical priority allowed` };
+            }
+        }
+        // Check weekly usage
         const rawUsage = state.usagePercent;
-        if (typeof rawUsage !== 'number' || !isFinite(rawUsage))
-            return true; // Bad data → fail open
+        if (typeof rawUsage !== 'number' || !isFinite(rawUsage)) {
+            return { allowed: true, reason: 'Invalid weekly data — fail open' };
+        }
         const usage = Math.max(0, Math.min(100, rawUsage));
         const { normal, elevated, critical, shutdown } = this.config.thresholds;
-        if (usage >= shutdown)
-            return false; // Nothing runs
+        if (usage >= shutdown) {
+            return { allowed: false, reason: `Weekly quota at ${usage}% — all jobs stopped` };
+        }
         if (usage >= critical) {
-            return priority === 'critical';
+            const ok = !priority || priority === 'critical';
+            return ok
+                ? { allowed: true, reason: `Weekly at ${usage}% — critical only` }
+                : { allowed: false, reason: `Weekly quota at ${usage}% — only critical priority runs` };
         }
         if (usage >= elevated) {
-            return priority === 'critical' || priority === 'high';
+            const ok = !priority || priority === 'critical' || priority === 'high';
+            return ok
+                ? { allowed: true, reason: `Weekly at ${usage}% — high+ only` }
+                : { allowed: false, reason: `Weekly quota at ${usage}% — only high+ priority runs` };
         }
         if (usage >= normal) {
-            return priority !== 'low';
+            const ok = !priority || priority !== 'low';
+            return ok
+                ? { allowed: true, reason: `Weekly at ${usage}% — medium+ only` }
+                : { allowed: false, reason: `Weekly quota at ${usage}% — low priority paused` };
         }
-        return true; // Below normal — everything runs
+        return { allowed: true, reason: 'Quota normal' };
     }
     /**
      * Write a quota state to the file (for collector scripts or manual updates).
@@ -126,6 +160,11 @@ export class QuotaTracker {
         const state = this.getState();
         if (!state)
             return 'normal';
+        // 5-hour at 95%+ is always 'stop' regardless of weekly
+        if (typeof state.fiveHourPercent === 'number' && state.fiveHourPercent >= 95)
+            return 'stop';
+        if (typeof state.fiveHourPercent === 'number' && state.fiveHourPercent >= 80)
+            return 'critical';
         const usage = state.usagePercent;
         const { normal, elevated, critical, shutdown } = this.config.thresholds;
         if (usage >= shutdown)
@@ -138,5 +177,55 @@ export class QuotaTracker {
             return 'reduce';
         return 'normal';
     }
+    /**
+     * Fetch quota status from a remote API (e.g., Dawn's /api/instar/quota).
+     * If the remote says canProceed=false, updates local state accordingly.
+     *
+     * This allows Instar agents to check a central quota authority before
+     * spawning sessions, preventing wasted attempts on exhausted machines.
+     *
+     * @param url - Full URL to the quota API (e.g., "https://dawn.bot-me.ai/api/instar/quota")
+     * @param apiKey - Authorization token (sent as Bearer header)
+     * @param timeoutMs - Request timeout (default 5000ms)
+     * @returns Remote quota status, or null on failure (fail-open)
+     */
+    async fetchRemoteQuota(url, apiKey, timeoutMs = 5000) {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const response = await fetch(url, {
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Accept': 'application/json',
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                console.warn(`[quota] Remote quota API returned ${response.status}`);
+                return null;
+            }
+            const data = await response.json();
+            // If remote says blocked, update local state to reflect it
+            if (!data.canProceed && typeof data.weeklyPercent === 'number') {
+                const state = this.getState() ?? {
+                    usagePercent: 0,
+                    lastUpdated: new Date().toISOString(),
+                };
+                state.usagePercent = data.weeklyPercent;
+                if (typeof data.fiveHourPercent === 'number') {
+                    state.fiveHourPercent = data.fiveHourPercent;
+                }
+                state.lastUpdated = new Date().toISOString();
+                this.cachedState = state;
+            }
+            return data;
+        }
+        catch (err) {
+            // Network failure, timeout, etc. — fail open
+            console.warn(`[quota] Remote quota check failed: ${err instanceof Error ? err.message : err}`);
+            return null;
+        }
+    }
 }
 //# sourceMappingURL=QuotaTracker.js.map

package/dist/scheduler/JobScheduler.d.ts

@@ -10,6 +10,7 @@
 import { SkipLedger } from './SkipLedger.js';
 import type { SessionManager } from '../core/SessionManager.js';
 import type { StateManager } from '../core/StateManager.js';
+import type { QuotaTracker } from '../monitoring/QuotaTracker.js';
 import type { MessagingAdapter } from '../core/types.js';
 import type { JobDefinition, JobSchedulerConfig, JobPriority } from '../core/types.js';
 import type { TelegramAdapter } from '../messaging/TelegramAdapter.js';
@@ -42,6 +43,8 @@ export declare class JobScheduler {
     private messenger;
     /** Optional Telegram adapter for job-topic coupling */
     private telegram;
+    /** Optional quota tracker for death classification cross-reference */
+    private quotaTracker;
     constructor(config: JobSchedulerConfig, sessionManager: SessionManager, state: StateManager, stateDir: string);
     /**
      * Set a messaging adapter for job completion notifications.
@@ -52,6 +55,12 @@ export declare class JobScheduler {
      * Every job gets its own topic — the user's window into the job.
      */
     setTelegram(adapter: TelegramAdapter): void;
+    /**
+     * Set the quota tracker for session death classification.
+     * When set, session deaths are cross-referenced with quota state
+     * to determine if they died from quota exhaustion.
+     */
+    setQuotaTracker(tracker: QuotaTracker): void;
     /**
      * Start the scheduler — load jobs, set up cron tasks, check for missed jobs.
      */

package/dist/scheduler/JobScheduler.js

@@ -11,6 +11,7 @@ import { Cron } from 'croner';
 import { execFileSync } from 'node:child_process';
 import { loadJobs } from './JobLoader.js';
 import { SkipLedger } from './SkipLedger.js';
+import { classifySessionDeath } from '../monitoring/QuotaExhaustionDetector.js';
 const PRIORITY_ORDER = {
     critical: 0,
     high: 1,
@@ -33,6 +34,8 @@ export class JobScheduler {
     messenger = null;
     /** Optional Telegram adapter for job-topic coupling */
     telegram = null;
+    /** Optional quota tracker for death classification cross-reference */
+    quotaTracker = null;
     constructor(config, sessionManager, state, stateDir) {
         this.config = config;
         this.sessionManager = sessionManager;
@@ -52,6 +55,14 @@ export class JobScheduler {
     setTelegram(adapter) {
         this.telegram = adapter;
     }
+    /**
+     * Set the quota tracker for session death classification.
+     * When set, session deaths are cross-referenced with quota state
+     * to determine if they died from quota exhaustion.
+     */
+    setQuotaTracker(tracker) {
+        this.quotaTracker = tracker;
+    }
     /**
      * Start the scheduler — load jobs, set up cron tasks, check for missed jobs.
      */
@@ -353,6 +364,24 @@ export class JobScheduler {
         catch {
             // Session may already be dead — that's fine
         }
+        // Classify death cause if session failed/was killed
+        let deathCause;
+        if (failed && output) {
+            const quotaState = this.quotaTracker?.getState() ?? null;
+            const classification = classifySessionDeath(output, quotaState);
+            deathCause = classification.cause;
+            this.state.appendEvent({
+                type: 'session_death_classified',
+                summary: `Session for "${job.slug}" classified as ${classification.cause} (${classification.confidence}): ${classification.detail}`,
+                timestamp: new Date().toISOString(),
+                metadata: {
+                    slug: job.slug,
+                    cause: classification.cause,
+                    confidence: classification.confidence,
+                    detail: classification.detail,
+                },
+            });
+        }
         // Build a summary message
         const duration = session.startedAt
             ? Math.round((Date.now() - new Date(session.startedAt).getTime()) / 1000)
@@ -361,7 +390,10 @@ export class JobScheduler {
             ? `${Math.floor(duration / 60)}m ${duration % 60}s`
             : `${duration}s`;
         let summary = `*Job Complete: ${job.name}*\n`;
-        summary += `Status: ${failed ? 'Failed' : 'Done'}\n`;
+        summary += `Status: ${failed ? 'Failed' : 'Done'}`;
+        if (deathCause && deathCause !== 'unknown')
+            summary += ` (${deathCause})`;
+        summary += '\n';
         if (duration > 0)
             summary += `Duration: ${durationStr}\n`;
         if (output) {

package/package.json

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