Session Lifecycle
Session management from activation through agent execution to completion. Execution profiles adapt based on quality gate performance.
Where Did We Leave Off?
Complex projects span multiple sessions. Without structured session management, you lose track of what was done, what's pending, and what decisions were made. Resuming means re-reading files, re-explaining context, and hoping nothing was lost. The AI has no concept of 'picking up where we left off.'
Session State Machine
Sessions begin when you activate the orchestrator with /chati and end with /chati exit. While active, all messages route through the orchestrator.
INACTIVE
No active session. User can start with /chati command.
ACTIVE
Session locked. All messages route through the orchestrator.
RUNNING
Current agent owns the conversation and processes its task.
HANDOFF
Agent output parsed. Two-layer handoff (YAML + artifact) prepared.
GATE EVAL
Quality gate evaluates output. Passes to next agent, retries, or completes.
Session Schema (session.yaml)
Session state lives in .chati/session.yaml. This file tracks everything needed to resume after interruption.
| Field | Type | Purpose |
|---|---|---|
| sessionId | UUID | Unique identifier for this session |
| currentAgent | string | Currently active agent in the pipeline |
| pipelinePhase | enum | Current pipeline phase (DISCOVER/PLAN/BUILD/DEPLOY) |
| executionProfile | enum | How actions execute: explore, guided, or autonomous |
| contextBracket | enum | Current token budget level (FRESH/MODERATE/DEPLETED/CRITICAL) |
| costTracking | object | Cumulative token usage and cost per provider |
| gateScores | object | Quality scores from each pipeline gate |
| handoffHistory | array | Ordered list of agent handoff records |
| activeMode | enum | Current operational mode (planning, build, deploy) |
| circuitBreaker | enum | Circuit breaker state (CLOSED, OPEN, HALF_OPEN) |
Execution Profile Flow
Sessions start in guided mode. When both QA gates pass at 95%+, the system can go autonomous. Safety net triggers revert to guided if problems come up.
EXPLORE
Read-only mode. Agents analyze, investigate, and suggest but perform no write operations. Safe for discovery.
GUIDED
Default profile. Agents propose actions and wait for user confirmation before writes. Balances safety with productivity.
AUTONOMOUS
Full autonomy. Agents execute without confirmation when quality gate scores meet thresholds. Requires dual QA approval.
Governance Modes
Planning Mode
Active during DISCOVER and PLAN phases. Agents can read everything but only write to the chati.dev/ directory.
Build Mode
Active during BUILD phase. Agents have full file system access to implement the solution.
Deploy Mode
Active during DEPLOY phase. Full access plus infrastructure configuration capabilities.
Safety Net Triggers
Five triggers automatically revert the system from autonomous to guided mode, preventing runaway execution.
Stuck Loop
Agent repeats the same action 3+ times without progress
Quality Drop
Gate score drops below threshold during execution
Scope Creep
Agent deviates from the defined task boundaries
Error Cascade
Multiple consecutive errors across different operations
User Override
Explicit user command to regain manual control
Frustration Detection
The PRISM engine monitors conversation patterns for signs of user frustration (repeated corrections, escalating tone, circular requests). When detected, agents automatically adapt their response style: shorter answers, more direct guidance, and fewer options to reduce cognitive load.
Model Fallback
When the primary model (opus) returns a 529 overload error, the system automatically falls back to sonnet for the current turn. The fallback is transparent to the user and recorded in session.yaml for cost tracking. Normal model selection resumes on the next turn.
Context Recovery
Two-level autonomous context recovery prevents quality loss when the context window is exhausted.
Smart Continuation
Auto-captures a structured digest on PreCompact events. Persists HOT and WARM memories, rebuilds context from the digest after compaction. Zero user interruption.
Autonomous Session Spawn
Spawns a new session when 3+ compactions occur, quality drops by more than 15%, or the bracket stays CRITICAL persistently. The new session inherits full context from the digest.