vibeostheog 0.25.54 → 0.26.0

package/CHANGELOG.md

@@ -1,3 +1,113 @@
+## 0.26.0
+- feat: add classify/escalate cascade API wiring (#398)
+- feat: rebuild dashboard home and session workspace (#389)
+- feat: dashboard orchestrator backend + UX overhaul + MiniLM routing (#384)
+- feat: learned flow rules from user corrections + content-aware pattern detection
+- feat: redesign dashboard as home-first shell
+- feat: port orchestrator frontend from vibeOScore
+- fix: active API health probe — no passive 60s fallback, +audit path safety
+- fix: local cascade escalation was discarded by any backend route, resolved_tier stuck at None (#412)
+- fix: footer tier label/depth-icon desync, silent fallback trip, broken dead imports (#411)
+- fix: isApiFallback() never self-heals, keeping BE non-authoritative for the session (#409)
+- fix: cascade route_path pinned at full pipeline forever, never deescalates (#407)
+- fix: remove dead cascade fields, footer model name follows escalated tier (#406)
+- fix: single source of truth for cascade tier + fix deescalation (#405)
+- fix: collapse cascade tier-routing to one source of truth, fix dead loop detector (#404)
+- fix: collapse cascade subagent routing to one source of truth (#403)
+- fix: use pending_escalation_tier for loop_break/web_search override (#402)
+- fix: FE consumes web_search and loop_break from BE classify response (#401)
+- fix: wire escalation re-route and loop context consumption (#399)
+- fix: collapse 3-painter footer architecture into 1 shared resolver + 1 degrade path (#396)
+- fix: cascade-aware model display in footer using trinity slot models (#395)
+- fix: move hardcoded big-pickle fallback after resolveTrinityDisplayModel in shell-env (#394)
+- fix: stop hardcoded opencode/big-pickle fallback from overriding real model in footer (#393)
+- fix: footer honesty — expired reroute pulse removed, cascade icon shows at depth 1 (#391)
+- fix: preserve native opencode mode selectors (#390)
+- fix: align fallback footer with turn truth (#388)
+- fix: align runtime footer and cascade truth (#387)
+- fix: footer honesty + pivot cache TTL + quality floor in syncControlSettings (#386)
+- fix: footer alert isApiFallback, session schema tier/model, cascade a… (#385)
+- fix: replace vitest skeletons with node:test to unbreak CI
+- fix: global agent config, session recording, and stale opencode config
+- fix: remove hardcoded footer mode branding
+- fix: preserve web search shell text for api tests
+- fix: update stale ~/.claude/ state paths to VIBEOS_HOME
+- fix: update stale ~/.claude/ state paths to VIBEOS_HOME
+- fix: durable dashboard snapshots + stale-proof MCP discovery (#371)
+- fix: cascade footer shows escalated tier + correct arrow count (#370)
+- fix: persist cascade depth from backend route so footer shows cascade icon (#369)
+- fix: make the cascade real — canonical blackbox records, live audit trail, durable bridges (#366)
+- fix: stop config.update/opencode.json mid-turn writes that abort OpenCode turns (#365)
+- fix: stop mid-turn opencode.json writes that abort OpenCode turns (#357)
+- fix: stop vibeultrax from over-triggering stall recovery (#354)
+- fix: clean up legacy config stubs before turns (#353)
+- fix: unify vibe primary agent topology (#352)
+- fix: add tool-call loop circuit-breaker to stop runaway bash poll loops (#350)
+- fix: remove VIBEOS_API_DISABLED=true persistence from disk (#348)
+- fix: allow explicit setting of embedded API token (#347)
+- fix: deploy script never overwrites VIBEOS_HOME/.env.production (#346)
+- fix: api hot-path deadline + blackbox state consolidation + spec contract (#345)
+- fix: persist cascade depth/root to blackbox state across turns (#343)
+- fix: prevent stale .js shadowing and cascade de-escalation (#342)
+- fix: consolidate runtime OpenCode home resolution to single ~/.opencode (#338)
+- fix: single source of truth for the footer — kill the "always cut" fallback (#331)
+- fix: force pipeline repair when manual mode pipeline is collapsed (#330)
+- fix: force pipeline repair when manual mode pipeline is collapsed
+- fix: footer bail-out + pipeline collapse (#329)
+- refactor: split state.ts into modules, fix resolved_tier freeze during API fallback (#413)
+- refactor: dedupe the 8-field loop-notice reset block in loop-state.ts (#410)
+- refactor: delete the dead ML learned-graph and the claim-verification wrapper (#408)
+- refactor: mode axis consolidation + footer display fixes (#383)
+- refactor: remove dead code and toy test (post-merge cleanup)
+- refactor: consolidate mode system to vibemax|vibeqmax|vibeultrax|vibelitex|raw
+- refactor: split maintainability boundaries into focused modules (#358)
+- refactor: consolidate safeJsonParse to one canonical helper (#356)
+- docs: update README for v0.26.0 Containment of Potential; add codename mapping in release.mjs
+- test: add cascade escalation and mode-router real tests + API shape c… (#400)
+- test: add SPEC §14 coverage tests and fix TS loader compilation (#397)
+- chore: untrack internal-only MD files from repo (#351)
+Fix dashboard home hierarchy and sidebar status (#392)
+Merge pull request #380 from DrunkkToys/refactor/learned-flow-patterns
+Merge pull request #379 from DrunkkToys/fix/global-config-dashboard
+Merge pull request #378 from DrunkkToys/codex/dashboard-home-mirror
+Fix footer integration test expectations
+Merge pull request #377 from DrunkkToys/codex/fix-vibeultrax-cheap-first-startup
+Fix syncControlSettings fallback slot scope
+Update README regime and feature counts
+Fix VibeUltraX cheap-first startup routing
+Merge pull request #376 from DrunkkToys/codex/fix-plugin-status-savings
+Hide footer backend icon during auth fallback
+Fix plugin registration, status fallback, and savings sync
+Merge pull request #375 from DrunkkToys/codex/minilm-authoritative-mode
+Use embedding selector for authoritative mode decisions
+Merge pull request #374 from DrunkkToys/codex/unify-dashboard-fastify
+Preserve health probe metadata in MCP status
+Add dashboard bridge write-behind sync
+Merge pull request #373 from DrunkkToys/codex/port-vibeoscore-orchestrator-dashboard
+fix cascade: complex prompts at any confidence route to brain tier (#368)
+Fix local loop authority (#367)
+Fix mega test loader paths and spec claims (#364)
+Narrow shell loop guard to polling (#363)
+Suppress repeated LOOPING notices (#362)
+Make LOOPING sticky across authoritative state writes (#361)
+Show cascade escalation labels (#360)
+Unify session events under VIBEOS_HOME (#359)
+Fix/api client consolidation (#355)
+Migrate test suite to TS and fix buildFooterAlert null crash (#344)
+Migrate repo to TS-only sources (#341)
+Codex/fix cascade authority (#340)
+Consolidate vibeOS skill install (#339)
+Bind vibe tiers to live OpenCode agents (#337)
+Fix VibeUltraX cheap-tier default via the OpenCode dropdown lever (#336)
+Fix VibeUltraX cascade with tier subagents (#335)
+Fix VibeUltraX live root state (#334)
+Fix VibeUltraX cascade routing (#333)
+Fix live control vector persistence (#332)
+Revert "fix: force pipeline repair when manual mode pipeline is collapsed"
+Fix blackbox session-id fragmentation freezing all sessions at INIT (#328)
+Fix footer runtime probe path (#327)
+
+
 ## 0.25.53
 - fix: add project/blackbox cards to home summary, fix template source detection, expand recommendations (#302)
 Merge release v0.25.52 into master

package/README.md

@@ -1,10 +1,13 @@
-# vibeOS for OpenCode -- Innocence v0.25.52
+# vibeOS for OpenCode -- Containment of Potential v0.26.0
+
+> **VIBEOS_HOME** = `/Users/drunkktoys/Library/Application Support/ai.opencode.desktop/vibeOS/`
+> All runtime state files live under `$VIBEOS_HOME` (set via `VIBEOS_HOME` env var on this machine).
 
 A quality-first control plane for AI-assisted coding.
 
 When AI coding is cheap, you use more of it. That is the upside of the current moment -- the marginal cost of a code suggestion has collapsed. But volume does not equal quality. The more you delegate to AI, the more often a mediocre suggestion slips through: a half-implemented fix, a fabricated API call, a test that passes only because the assertions are stubs. The quality problem gets worse as the cost problem gets better. vibeOS exists to solve the quality problem. The savings are a side effect.
 
-OpenCode Desktop gives you access to the most capable language models ever created -- Opus, Sonnet, DeepSeek v4 Pro -- but running them on every single turn adds up fast. More importantly, routing every turn through the most expensive model does not guarantee the best output. A cheap model proposing, a mid-tier model reviewing, and a top-tier model polishing often produces better results than a single expensive model guessing alone. vibeOS makes that routing decision automatically, on every turn, based on what you are actually doing.
+OpenCode Desktop gives you access to the most capable language models ever created -- Opus, Sonnet, DeepSeek v4 Pro -- but running them on every single turn adds up fast. More importantly, routing every turn through the most expensive model does not guarantee the best output. vibeOS keeps one primary `vibe` agent in the dropdown, lets same-provider tier changes swap in-thread, and delegates cross-provider tier work to tier subagents without rewriting the active agent every turn.
 
 The real system is smaller than the feature list makes it sound:
 
@@ -33,17 +36,17 @@ The lie detector flags when the assistant claims success without evidence. The l
 
 ## The Cascade Engine
 
-vibeOS uses a three-tier cascade to route every turn through the cheapest model that can produce a quality result.
+vibeOS uses a single primary `vibe` agent plus three tier subagents to route every turn through the cheapest model that can produce a quality result.
 
 ### How It Works
 
-1. **Cheap proposal** -- Your configured cheap slot generates an initial response (e.g., a local Ollama model via `vibe set cheap magiccoder:7b`, or any API model).
-2. **Flash review** -- A mid-tier model (DeepSeek v4 Flash) critiques and refines the proposal.
-3. **Pro polish** -- The brain-tier model (DeepSeek v4 Pro) applies a final quality pass on complex sections.
+1. **Cheap proposal** -- The unified `vibe` primary starts on your configured cheap slot (e.g., a local Ollama model via `vibe set cheap magiccoder:7b`, or any API model).
+2. **Flash review** -- The medium tier runs as a subagent and critiques/refines the proposal without changing the dropdown agent.
+3. **Pro polish** -- The brain tier runs as a subagent on complex sections; cross-provider work delegates there instead of flipping the active agent.
 
 Not every turn goes through all three stages. The cascade router estimates input difficulty and routes simple queries directly to the cheap tier. Complex reasoning, multi-file edits, and ambiguous instructions escalate to medium or brain. The router learns from session outcomes and calibrates its thresholds over time.
 
-Benchmarked at **107% of raw brain quality at 58% of cost**. Local inference is free; only the Flash and Pro stages incur API costs. This is the first routing strategy that Pareto-dominates the raw brain baseline -- better quality, lower cost.
+Benchmarked at **107% of raw brain quality at 58% of cost**. Local inference is free; only the Flash and Pro stages incur API costs. This is the first routing strategy that Pareto-dominates the raw brain baseline -- better quality, lower cost, without per-turn agent churn.
 
 ### Research Foundation
 
@@ -51,14 +54,16 @@ The cascade shape follows the general LLM routing literature, but the live sourc
 
 ### VibeBoX Decision Engine
 
-At the core of vibeOS is a real-time decision engine that classifies every user turn into one of seven sub-regimes:
+At the core of vibeOS is a real-time decision engine that classifies every user turn into one of fourteen sub-regimes:
 
 - **INIT / DIVERGENT / EXPLORING** -- You are learning the codebase, asking questions, browsing. cheap model, relaxed enforcement. Stay out of your way.
-- **REFINING** -- You are iterating on a solution. Default mode: VibeUltraX, auto-escalate on complexity.
+- **REFINING / IMPLEMENTING / DESIGNING** -- You are iterating on a solution or actively building. Default mode: VibeUltraX, auto-escalate on complexity.
+- **RESEARCH / REVIEWING** -- You are investigating, comparing, or checking work. Routing and enforcement tighten as evidence requirements increase.
 - **CONVERGING / CLOSED** -- You are finalizing. Full quality mode, brain tier, strict enforcement and flow checks.
-- **LOOPING** -- You are stuck. Speed mode, medium tier, cycle-breaking interventions.
+- **LOOPING / ESCALATED** -- You are stuck or the session needs intervention. Speed mode or hard escalation paths activate to break cycles.
+- **FORENSIC / AUDIT** -- You are doing deep investigation or security-style review. Brain tier, strict enforcement, detailed verification.
 
-Classification uses 11 derived features per turn: message length, code block density, question ratio, urgency signals, sentiment, complexity estimate, repetition, instruction density, and more. Four escalating intervention levels prevent infinite loops. PIVOT/SWITCH detection recognizes context changes and injects scope-confirmation directives.
+For VibeMaX, feature extraction currently yields 14 numeric features per turn: 8 normalized metrics plus 6 raw/boolean indicators. Four escalating intervention levels prevent infinite loops. PIVOT/SWITCH detection recognizes context changes and injects scope-confirmation directives.
 
 When the VibeBoX is disabled, a lightweight classifyTurnSimple fallback distinguishes Q&A from implementation intent using regex patterns.
 
@@ -68,7 +73,7 @@ A real-time stress scoring pipeline analyzes user messages for frustration signa
 
 ### Pattern Learner
 
-Per-project friction and routine tracking. The learner watches repeated tool failures, recovery loops, and stable workflows, then stores the result locally first. Cross-project hints are merged later into `global-learning.json` so the client can stay small while still learning.
+Per-project friction and routine tracking. The learner watches repeated tool failures, recovery loops, and stable workflows, then stores the result locally first. Cross-project hints are merged later into `VIBEOS_HOME/global-learning.json` so the client can stay small while still learning.
 
 ### Context Compression
 
@@ -107,14 +112,14 @@ The smart cache predicts whether a tool query will hit scratchpad cache before e
 
 The prediction engine (`predictCacheHit`) computes a confidence score and returns whether caching is worthwhile, estimated savings, and the most similar cached entries. Per-tool hit rates are tracked with exponential decay (DECAY = 0.9) so recent performance matters more than historical averages.
 
-Cache state persists across sessions in `~/.claude/global-learning.json` with a 7-day TTL eviction. The prediction results feed into the delegation enforcer's cost calculations and appear in the live footer savings display.
+Cache state persists across sessions in `VIBEOS_HOME/global-learning.json` with a 7-day TTL eviction. The prediction results feed into the delegation enforcer's cost calculations and appear in the live footer savings display.
 
 ### Pivot and Counter-Pivot
 
 Two complementary mechanisms manage context transitions:
 
 **Forward pivot** -- Detects when you abruptly change topic mid-session. Uses a composite score of word-overlap distance, instruction-density delta, message-length ratio, and action-type change. Fires when `pivotScore > 0.45`. When detected:
-1. Snapshots the current workflow (intent, files, decisions, blockers, code) to `~/.claude/.vibeos-pivot-cache.json`
+1. Snapshots the current workflow (intent, files, decisions, blockers, code) to `$VIBEOS_HOME/.vibeos-pivot-cache.json`
 2. Downgrades mode to budget (cheap tier, thinking off, relaxed enforcement)
 3. Injects a context-shift directive into the system prompt
 
@@ -138,7 +143,7 @@ The savings are real and measurable. Every write/edit on the brain tier is inter
 | Opus -> Sonnet | $0.0264 | $0.26 | $2.64 | $26.40 |
 | Sonnet -> Haiku | $0.0044 | $0.04 | $0.44 | $4.40 |
 
-The running total is persisted in ~/.claude/delegation-state.json and displayed in the live footer. Cache savings are tracked separately under cache_savings_usd.
+The running total is persisted in $VIBEOS_HOME/delegation-state.json and displayed in the live footer. Cache savings are tracked separately under cache_savings_usd.
 
 ### Model Tiers
 
@@ -157,28 +162,30 @@ DeepSeek Chat costs $0/turn when routed through the Direct DeepSeek provider (no
 
 | Policy | Quality vs Brain | Cost vs Brain | Savings | Method |
 |--------|-----------------|--------------|---------|--------|
-| VibeUltraX | 107% | 0.58x | 42% | cheap -> medium -> brain cascade |
+| VibeUltraX | 107% | 0.58x | 42% | vibe primary + tier subagents |
 | VibeQMaX | ~100% | 0.50x | 50% | same model, framework optimizations |
-| Raw Brain | 100% | 1.00x | - | baseline |
 | VibeMaX | ~75% | 0.18x | 82% | trained cascade (conservative escalate) |
+| VibeLiteX | ~40% | 0.00x | 100% | direct cheap routing |
 | Budget | ~40% | 0.00x | 100% | direct routing |
 
-**VibeUltraX** -- Default mode. Cheap slot proposes, medium reviews, brain refines. 107% quality at 58% cost.
+**VibeUltraX** -- Default mode. The unified `vibe` primary starts on cheap, medium and brain run as subagents, and same-provider escalations stay in-thread. 107% quality at 58% cost.
 
 **VibeQMaX** -- Routes strategic turns through v4 Pro with full thinking, strict enforcement, strict flow checks, and quality TDD. Write/edit delegated per enforcement rules. Blended cost ~$0.00029/turn (50% of brain baseline).
 
 **VibeMaX** -- ML-optimized medium mode. Routes through v4 Flash with a random forest classifier (29 trees, gini-split, trained on telemetry) that decides each turn. ~75% quality at 18% cost.
 
+**VibeLiteX** -- Cheap direct routing with relaxed enforcement. Ideal for exploration and Q&A.
+
 **Budget** -- DeepSeek Chat. Direct routing. ~40% quality at zero cost.
 
 ### Mode Configuration
 
 | Mode | Model | Thinking | Enforcement | Flow | TDD |
 |------|-------|----------|-------------|------|-----|
-| Raw Brain | v4 Pro | full | - | - | - |
 | VibeQMaX | v4 Pro | full | strict | strict | quality |
-| VibeUltraX | cascade (cheap->medium->brain) | auto | auto | auto | auto |
+| VibeUltraX | vibe primary + tier subagents | auto | auto | auto | auto |
 | VibeMaX | v4 Flash (auto-escalate) | auto | auto | auto | auto |
+| VibeLiteX | cheap | off | relaxed | audit | lazy |
 | Speed | v4 Flash | off | relaxed | audit | lazy |
 | Budget | DeepSeek Chat | off | relaxed | audit | lazy |
 
@@ -201,11 +208,11 @@ Stress > 1.5 escalates any regime to quality mode regardless of the above mappin
 | Delegation enforcement | Blocks write/edit on brain tier, routes to cheaper tiers transparently |
 | Live savings footer | Tier, provider, model name, total savings, mode -- one line of reassurance |
 | Web dashboard | Session-first SolidJS SPA with executive Home summary, session actions, per-session templates, polling refresh for model split, savings, session history, controls |
-| Trinity runtime | Update tier slots through the native OpenCode config path, change optimization mode, toggle subsystems live |
+| Trinity runtime | Update tier slots and keep the unified vibe primary plus tier subagents synced through the native OpenCode config path, change optimization mode, toggle subsystems live |
 | Flow enforcer | Pattern-rule checks on write/edit. Extracts TODO/FIXME into append-only queue. |
 | TDD enforcer | Auto-creates test skeletons for changed source. Strict mode fails TODO tests. |
 | Pattern learner | Tracks recurring struggle/routine patterns per project, cross-project too |
-| VibeBoX | 7 sub-regimes, 11 features per turn, loop intervention, PIVOT/SWITCH detection |
+| VibeBoX | 14 sub-regimes, 14 features per turn, loop intervention, PIVOT/SWITCH detection |
 | Stress-aware routing | Real-time stress scoring, auto-escalation, system prompt inoculation |
 | Cache savings | Separate cache_savings_usd tracking for scratchpad cache hits |
 | Report tools | report-save, report-list, report-read, research-audit |
@@ -222,10 +229,13 @@ Stress > 1.5 escalates any regime to quality mode regardless of the above mappin
 | Claim verification | Scans assistant output for made-up references, validates against codebase |
 | Token compression | Web fetch output stripped to 30% of original size -- verbose lines, bullet prefixes, and blank lines collapsed. Tool output history compressed to cold-storage references after the hot window (last 10 messages). Project memory condensed to single-line directives for system prompts. |
 | Rotation memory | Scratchpad files age through a four-stage lifecycle: fresh (< 5 min, full content), warm (5 min - 24 hr, 500-char summary), cold (24 - 48 hr, 200-char summary), expired (> 48 hr, deleted). Rotation runs opportunistically on every tool execution, throttled to once per minute. Cache hits degrade gracefully over time instead of failing abruptly. |
-| Smart cache | Predicts whether a tool query will hit scratchpad cache using composite similarity scoring (Jaccard + cosine bigram + weighted keyword overlap). Per-tool hit rates tracked with exponential decay. Estimated savings calculated and displayed in the live footer. Cache entries persisted across sessions via global-learning.json with 7-day TTL eviction. |
+| Smart cache | Predicts whether a tool query will hit scratchpad cache using composite similarity scoring (Jaccard + cosine bigram + weighted keyword overlap). Per-tool hit rates tracked with exponential decay. Estimated savings calculated and displayed in the live footer. Cache entries persisted across sessions via `VIBEOS_HOME/global-learning.json` with 7-day TTL eviction. |
 | Pivot / counter-pivot | Detects when you switch topics mid-session (forward pivot) and when you return to a previously abandoned workflow (counter-pivot). Forward pivots snapshot the old workflow context and downgrade to budget mode. Counter-pivots restore files, decisions, blockers, and code snippets from cached workflow snapshots into the system prompt. |
 | Deferred reports | saveReport deferred to setTimeout to avoid blocking tool output |
 | Stress gauge footer | Live indicator in footer -- ▁▂▃▅▆█ (none/minimal/calm/elevated/high/critical) |
+| Cascade escalation API | classifyTurn + escalateTurn endpoints wired through the cascade pipeline with real-time tier resolution |
+| Backend-authoritative slot sync | Active API health probe syncs slot state from backend authority without passive fallback |
+| SPEC §14 coverage | Certified test coverage for cascade tier-routing, deescalation, mode-router, and API shape compliance |
 
 ## Install
 
@@ -259,8 +269,8 @@ Local dev checkout:
 | `vibe set brain\|medium\|cheap [model=<model_id>]` | Switch active model tier or override slot |
 | `vibe brain\|medium\|cheap` | Shorthand tier switch |
 | `vibe enable|disable` | Toggle plugin on/off |
-| `vibe mode budget|quality|speed|longrun|auto|balanced|audit|forensic` | Set optimization mode |
-| `vibe thinking full|brief|off` | Reasoning depth |
+| `vibe mode budget\|quality\|speed\|longrun\|auto\|balanced\|audit\|forensic\|vibeultrax\|vibeqmax\|vibemax\|vibelitex` | Set optimization mode (generic or branded) |
+| `vibe thinking full\|brief\|off` | Reasoning depth |
 | `vibe enforce on|off` | Toggle delegation enforcement |
 | `vibe lock on|off` | Freeze model for session |
 | `vibe flow on|off` | Toggle flow enforcer |
@@ -271,6 +281,7 @@ Local dev checkout:
 | `vibe rebuild` | Re-detect models from all providers |
 | `vibe project` | Per-project analytics |
 | `vibe patterns` / `vibe patterns clear` / `vibe patterns suggest` | Pattern inspection |
+| `vibe axis [status\|reset\|<name> <value>]` | Axis overrides for enforcement, flow, tdd, tier, thinking, context7_urgency, wbp_verbosity, websearch |
 | `vibe todo` / `vibe todo-done <id>` / `vibe todo-sync` | View pending todos, mark done, sync flow todos |
 | `vibe verify-claims` | Audit recent claim output against cascade evidence |
 | `vibe diagnose` | Health check |
@@ -289,22 +300,24 @@ Local dev checkout:
 
 ### Architecture
 
-vibeOS hooks into OpenCode Desktop through 8 extension points:
+vibeOS hooks into OpenCode Desktop through 10 extension points:
 
 | Hook | Purpose |
 |------|---------|
 | experimental.text.complete | Appends footer to assistant responses |
 | experimental.chat.messages.transform | Injects delegation protocol content |
 | experimental.chat.system.transform | Injects cost optimization, stress inoculation, enforcement directives |
+| experimental.chat.params | Modifies chat parameters before requests |
+| experimental.chat.headers | Injects custom HTTP headers into chat requests |
 | tool.execute.before | Blocks write/edit on brain tier |
 | tool.execute.after | Injects delegation UI notes |
 | message.updated | Fallback footer for versions without text.complete |
 | experimental.session.compacting | Preserves savings state |
 | shell.env | Injects OPENCODE_MODEL_TIER and OPENCODE_MODEL |
 
-### State Files (~/.claude/)
+### State Files (`VIBEOS_HOME/`)
 
-The plugin persists state to ~/.claude/ for cross-session continuity:
+The plugin persists state to `VIBEOS_HOME/` for cross-session continuity:
 
 - **delegation-state.json** -- Sessions, warns, cache hits, lifetime totals
 - **model-tiers.json** -- Brain/medium/cheap model IDs
@@ -320,10 +333,6 @@ Core features work fully offline: model tier classification, static pricing, str
 
 Remote API (api.vibetheog.com) enables: bootstrap token exchange, advanced VibeBoX with full session history, dynamic per-prompt delegation, cross-session calibration, live pricing fetch, learned subagent routing. Falls back gracefully when unreachable.
 
-### What Is Missing For A True Session Orchestrator
-
-The live dashboard now covers the executive Home summary, session actions, and session-scoped templates. Still missing: session versioning/undo, template versioning, batch operations, live push transport, session comparison, and export/import.
-
 ### Live Footer
 
 The footer is the primary status line, appended to every assistant response. It surfaces model assignment, savings, mode, alerts, and session metrics in a single line.
@@ -406,6 +415,19 @@ The footer is the primary status line, appended to every assistant response. It
 | ⟡ medium | Active slot changed to medium this turn |
 | ⟡ brain | Active slot changed to brain this turn |
 
+#### Alert Tags
+
+The alert is part of the one footer (it is **not** a separate line). When present it renders
+after the enforcement tags and before the stress gauge. Multiple alerts join with ` · `.
+This table is the single source of truth — `buildFooterAlert()` must match it exactly.
+
+| Alert | Trigger |
+|-------|---------|
+| ⚠ api degraded | API latency is degraded / the backend is unhealthy this turn |
+| ⚠ switch pending | A tier switch is deferred and will apply at the next turn boundary |
+| ⚠ model drift | The live model is outside the cascade tiers and differs from the expected slot model |
+| ⚠ model unreachable | The last model call failed with a network error (EHOSTUNREACH / ENOTFOUND / ETIMEDOUT) |
+
 **Segments (left to right):**
 
 | Segment | Format | Example | Meaning |
@@ -418,22 +440,39 @@ The footer is the primary status line, appended to every assistant response. It
 | Brand + mode label | VibeBrand . modeLabel | VibeUltraX . Quality | Requested mode + regime-derived label |
 | Cascade icon | >>> or >> | >>> | VibeUltraX cascade depth >= 3 |
 | Enforcement tags | guarded, flow steady, tests live | guarded | Guard state summary |
+| Alert tags | ⚠ alert · ⚠ alert | ⚠ model drift | Live status alerts (see Alert Tags) |
 | Stress gauge | gaugeChar | _ | Current stress level |
 | Vector pulse | slot | cheap | Active slot changed this turn |
 
-Controls: `vibe status` for full state, `vibe enable/disable` to toggle. Persisted in ~/.claude/delegation-state.json.
+Controls: `vibe status` for full state, `vibe enable/disable` to toggle. Persisted in $VIBEOS_HOME/delegation-state.json.
 
 ### Environment Variables
 
 | Variable | Default | Effect |
 |----------|---------|--------|
+| VIBEOS_HOME | ~/.vibeos | Runtime state directory |
 | VIBEOS_API_URL | https://api.vibetheog.com | Remote API base URL |
 | VIBEOS_API_TOKEN | unset | Remote API auth |
-| VIBEOS_API_DISABLED | false | Invalidate alpha token |
 | VIBEOS_API_BOOTSTRAP_TOKEN | unset | Bootstrap exchange |
-| VIBEOS_API_ENABLED | true | Set false for local-only |
-| CLAUDE_CREDIT_PERCENT | 100 | Credit override |
 | VIBEOS_MCP_PORT | 3001 | MCP server port |
+| VIBEOS_BUILD_CHANNEL | alpha | Build channel for API client |
+| VIBEOS_DEBUG | unset | Verbose debug logging |
+| VIBEOS_DEBUG_INTERNALS | unset | Internal state debug logging |
+| VIBEOS_DEBUG_DELEGATION | unset | Delegation enforcer debug logging |
+| VIBEOS_DEBUG_FOOTER | unset | Footer builder debug logging |
+| VIBEOS_DEBUG_LOGS | unset | Flow enforcer debug logging |
+| VIBEOS_DEBUG_STDERR | unset | Flow enforcer stderr debug logging |
+| VIBEOS_FLOW_RULES_PATH | unset | Custom flow rules file path |
+| VIBEOS_DASHBOARD_SYNC_MS | 20000 | Dashboard polling interval (ms) |
+| VIBEOS_ACTIVE_PROBE_MS | 10000 | Backend health probe interval (ms) |
+| VIBEOS_REMOTE_LATENCY_DEGRADE_MS | 800 | Latency threshold for degraded alert (ms) |
+| VIBEOS_REMOTE_LATENCY_DEGRADE_COOLDOWN_MS | 120000 | Cooldown between degraded alerts (ms) |
+| VIBEOS_VIBEMAX_MODEL_PATH | unset | Custom VibeMaX model path |
+| VIBEOS_OPENCODE_DESKTOP_HOME | unset | OpenCode Desktop home override |
+| VIBEOS_OPENCODE_HOME | unset | OpenCode config home override |
+| VIBEOS_API_MASTER_KEY | unset | API master key for backend auth |
+| VIBEOS_BACKEND_HEALTH_URL | unset | Custom backend health check URL |
+| CLAUDE_CREDIT_PERCENT | 50 | Credit override percentage |
 
 ### Troubleshooting
 

package/bin/setup.js

@@ -1,47 +1,193 @@
 #!/usr/bin/env node
 
-import { execSync } from "node:child_process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+// src/bin/setup.ts
+import { execFileSync } from "node:child_process";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync2, renameSync as renameSync2 } from "node:fs";
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveOpenCodeHome, resolveOpenCodeHomes } from "../scripts/lib/opencode-homes.mjs";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const root = resolve(__dirname, "..");
-const args = process.argv.slice(2);
-const command = args.find(a => !a.startsWith("-")) ?? "setup";
-const isInstallCommand = command === "setup" || command === "set";
-const isProject = args.includes("--project");
-const isYes = args.includes("--yes") || args.includes("-y");
+// scripts/lib/opencode-homes.mjs
+import { join } from "node:path";
+import { homedir } from "node:os";
+function resolveOpenCodeHomes({ home = homedir() } = {}) {
+  const override = process.env.VIBEOS_OPENCODE_HOME;
+  if (override) return [override];
+  return [join(home, ".opencode")];
+}
+function resolveOpenCodeHome(opts = {}) {
+  return resolveOpenCodeHomes(opts)[0];
+}
 
+// scripts/lib/vibe-tier-agents.mjs
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+var VIBE_TIER_AGENT_BY_SLOT = {
+  cheap: "vibe-cheap",
+  medium: "vibe-medium",
+  brain: "vibe-brain"
+};
+var VIBE_PRIMARY_AGENT = "vibe";
+var NATIVE_OPENCODE_AGENTS = ["build", "plan", "vibe"];
+function isNativeOpenCodeAgent(value) {
+  return NATIVE_OPENCODE_AGENTS.includes(String(value || "").trim().toLowerCase());
+}
+function normalizeNativeOpenCodeAgent(value, fallback = VIBE_PRIMARY_AGENT) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return isNativeOpenCodeAgent(normalized) ? normalized : fallback;
+}
+function readJson(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf8");
+    const cleaned = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    const parsed = JSON.parse(cleaned);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function readTiers(home = homedir2()) {
+  return readJson(join2(process.env.VIBEOS_HOME || join2(home, ".claude"), "model-tiers.json"));
+}
+function primaryAgent(existing = {}) {
+  const next = {
+    ...existing && typeof existing === "object" ? existing : {},
+    description: "VibeUltraX primary agent",
+    mode: "primary",
+    permission: {
+      read: "allow",
+      edit: "allow",
+      glob: "allow",
+      grep: "allow",
+      list: "allow",
+      bash: "allow",
+      task: "allow",
+      webfetch: "allow",
+      websearch: "allow",
+      ...existing?.permission && typeof existing.permission === "object" ? existing.permission : {}
+    }
+  };
+  delete next.model;
+  return next;
+}
+function tierAgent(slot, model, existing = {}) {
+  return {
+    ...existing && typeof existing === "object" ? existing : {},
+    description: `VibeUltraX ${slot} tier subagent`,
+    mode: "subagent",
+    model,
+    permission: {
+      read: "allow",
+      edit: "allow",
+      glob: "allow",
+      grep: "allow",
+      list: "allow",
+      bash: "allow",
+      task: "allow",
+      webfetch: "allow",
+      websearch: "allow",
+      ...existing?.permission && typeof existing.permission === "object" ? existing.permission : {}
+    }
+  };
+}
+function installVibeTierAgentsInConfig(config, tiers = readTiers()) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) return false;
+  const trinity = tiers?.trinity || {};
+  config.$schema ||= "https://opencode.ai/config.json";
+  config.agent = config.agent && typeof config.agent === "object" ? config.agent : {};
+  let changed = false;
+  const existingPrimary = config.agent[VIBE_PRIMARY_AGENT];
+  const nextPrimary = primaryAgent(existingPrimary);
+  if (JSON.stringify(existingPrimary || null) !== JSON.stringify(nextPrimary)) {
+    config.agent[VIBE_PRIMARY_AGENT] = nextPrimary;
+    changed = true;
+  }
+  const nextDefaultAgent = normalizeNativeOpenCodeAgent(String(config.default_agent || "").trim() || VIBE_PRIMARY_AGENT);
+  if (config.default_agent !== nextDefaultAgent) {
+    config.default_agent = nextDefaultAgent;
+    changed = true;
+  }
+  for (const slot of ["cheap", "medium", "brain"]) {
+    const model = String(trinity?.[slot]?.oc || "").trim();
+    const name = VIBE_TIER_AGENT_BY_SLOT[slot];
+    if (!model || !name) continue;
+    const existing = config.agent[name];
+    const next = tierAgent(slot, model, existing);
+    if (JSON.stringify(existing || null) !== JSON.stringify(next)) {
+      config.agent[name] = next;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+// scripts/lib/plugin-config.mjs
+import { existsSync as existsSync2 } from "node:fs";
+import { resolve } from "node:path";
+function resolveVibeOSPluginRef(home) {
+  return resolve(home, "plugins", "vibeOS.js");
+}
+function normalizeVibeOSPluginRefs(pluginList, canonicalPluginRef) {
+  const refs = Array.isArray(pluginList) ? pluginList : [];
+  const kept = [];
+  let hasCanonical = false;
+  for (const ref of refs) {
+    if (typeof ref !== "string") {
+      kept.push(ref);
+      continue;
+    }
+    if (!ref.includes("vibeOS")) {
+      kept.push(ref);
+      continue;
+    }
+    const normalized = resolve(ref);
+    if (normalized === canonicalPluginRef || ref === canonicalPluginRef) {
+      if (!hasCanonical) {
+        hasCanonical = true;
+        kept.push(canonicalPluginRef);
+      }
+      continue;
+    }
+    if (existsSync2(normalized)) continue;
+  }
+  if (!hasCanonical) kept.push(canonicalPluginRef);
+  return kept;
+}
+
+// src/bin/setup.ts
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+var root = resolve2(__dirname, "..");
+var args = process.argv.slice(2);
+var command = args.find((a) => !a.startsWith("-")) ?? "setup";
+var isInstallCommand = command === "setup" || command === "set";
+var isProject = args.includes("--project");
+var writeLine = (text = "") => {
+  process.stdout.write(text + "\n");
+};
 if (!isInstallCommand || args.includes("--help") || args.includes("-h")) {
   console.error("Usage: npx vibeostheog set [--project]");
   console.error("       npx vibeostheog setup [--project]");
   process.exit(1);
 }
-
-console.log("");
-console.log("vibeOS — cost-aware delegation enforcer for OpenCode");
-console.log("");
-console.log("Installing to:");
-for (const h of resolveOpenCodeHomes({ cwd: process.cwd() })) console.log("  " + h);
-console.log("");
-
-// Deploy plugin files to ~/.config/opencode/plugins/ and register globally
-const deployScript = resolve(root, "scripts", "deploy.mjs");
-if (!existsSync(deployScript)) {
+writeLine();
+writeLine("vibeOS \u2014 cost-aware delegation enforcer for OpenCode");
+writeLine();
+writeLine("Installing to:");
+for (const h of resolveOpenCodeHomes({ cwd: process.cwd() })) writeLine("  " + h);
+writeLine();
+var deployScript = resolve2(root, "scripts", "deploy.mjs");
+if (!existsSync3(deployScript)) {
   console.error("Fatal: scripts/deploy.mjs not found at", deployScript);
   process.exit(1);
 }
-execSync(`node "${deployScript}"`, { stdio: "inherit", cwd: process.cwd() });
-
-// For per-project setup, also register in project-level opencode.json
+execFileSync(process.execPath, [deployScript], { stdio: "inherit", cwd: process.cwd() });
 if (isProject) {
-  const configPath = resolve(process.cwd(), "opencode.json");
+  const configPath = resolve2(process.cwd(), "opencode.json");
   let config = {};
-  if (existsSync(configPath)) {
+  if (existsSync3(configPath)) {
     try {
-      config = JSON.parse(readFileSync(configPath, "utf8"));
+      config = JSON.parse(readFileSync2(configPath, "utf8"));
     } catch {
       config = {};
     }
@@ -50,15 +196,14 @@ if (isProject) {
   if (!config.$schema) config.$schema = "https://opencode.ai/config.json";
   if (!Array.isArray(config.plugin)) config.plugin = [];
   const installHome = resolveOpenCodeHome({ cwd: process.cwd() });
-  const pluginRef = resolve(installHome, "plugins", "vibeOS.js");
-  config.plugin = config.plugin.filter((p) => !(typeof p === "string" && p.includes("vibeOS")));
-  if (!config.plugin.includes(pluginRef)) {
-    config.plugin.push(pluginRef);
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-  }
-  console.log(`vibeOS registered in ${configPath}`);
+  const pluginRef = resolveVibeOSPluginRef(installHome);
+  config.plugin = normalizeVibeOSPluginRefs(config.plugin, pluginRef);
+  installVibeTierAgentsInConfig(config);
+  mkdirSync2(dirname2(configPath), { recursive: true });
+  const tmp = `${configPath}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync2(tmp, JSON.stringify(config, null, 2) + "\n");
+  renameSync2(tmp, configPath);
+  writeLine(`vibeOS registered in ${configPath}`);
 }
-
-console.log("");
-console.log("Done. Restart OpenCode to activate the plugin.");
+writeLine();
+writeLine("Done. Restart OpenCode to activate the plugin.");