orchestrix-yuri 3.3.1 → 3.5.0

package/README.md

@@ -8,10 +8,10 @@ User describes idea → Yuri drives: Create → Plan → Develop → Test → De
 
 ## How It Works
 
-Yuri is a [Claude Code skill](https://code.claude.com/docs/en/skills) + Channel Gateway. It can be used in two ways:
+Yuri is a [Claude Code skill](https://code.claude.com/docs/en/skills) + Channel Gateway. Two ways to use:
 
 1. **Terminal mode** — activate `/yuri` inside any Claude Code session
-2. **Telegram mode** — chat with Yuri via Telegram bot, backed by a persistent tmux Claude Code session
+2. **Telegram mode** — chat with Yuri via Telegram bot
 
 | Phase | What Yuri Does | Agents Involved |
 |-------|---------------|-----------------|
@@ -34,35 +34,38 @@ Yuri is a [Claude Code skill](https://code.claude.com/docs/en/skills) + Channel
 ### Method A: From npm (recommended)
 
 ```bash
-# Install globally
 npm install -g orchestrix-yuri
-
-# Initialize skill + global memory
 orchestrix-yuri install
-
-# Start Telegram gateway
-orchestrix-yuri serve --telegram-token "YOUR_BOT_TOKEN"
+orchestrix-yuri start --token "YOUR_BOT_TOKEN"   # first time, saves token
+orchestrix-yuri start                              # from now on
 ```
 
 ### Method B: From source
 
 ```bash
-git clone https://github.com/anthropics/orchestrix-yuri.git
+git clone https://github.com/dorayo/orchestrix-yuri.git
 cd orchestrix-yuri
 npm install
-
-# Initialize skill + global memory
 node bin/install.js install
-
-# Start Telegram gateway
-node bin/serve.js --telegram-token "YOUR_BOT_TOKEN"
+node bin/serve.js --token "YOUR_BOT_TOKEN"
 ```
 
 ### What `install` does
 
 - Copies the Yuri skill to `~/.claude/skills/yuri/`
-- Initializes global memory at `~/.yuri/` (identity, boss profile, portfolio registry, focus, wisdom)
-- Creates channel config at `~/.yuri/config/channels.yaml`
+- Initializes global memory at `~/.yuri/` (identity, boss profile, portfolio, focus, wisdom)
+- Writes a bootstrap signal so Yuri greets you on first interaction
+
+## CLI Commands
+
+```bash
+orchestrix-yuri install                # Install Yuri skill + global memory
+orchestrix-yuri start                  # Start the Channel Gateway
+orchestrix-yuri start --token TOKEN    # Start & save Telegram Bot token (first time)
+orchestrix-yuri stop                   # Stop the running gateway
+orchestrix-yuri status                 # Show gateway status + cost tracking
+orchestrix-yuri --version              # Show version
+```
 
 ## Usage
 
@@ -74,168 +77,130 @@ In any Claude Code session:
 /yuri
 ```
 
-Then either describe your project idea in natural language, or use a specific command:
+### Telegram Mode
 
 | Command | Description |
 |---------|-------------|
-| `*create` | Create a new project (Phase 1) |
-| `*plan` | Start/resume project planning (Phase 2) |
-| `*develop` | Start/resume automated development (Phase 3) |
-| `*test` | Start/resume smoke testing (Phase 4) |
-| `*deploy` | Start/resume deployment (Phase 5) |
-| `*status` | Show current project phase and progress |
-| `*resume` | Resume from last saved checkpoint |
-| `*change "{desc}"` | Handle mid-project requirement change |
-
-### Telegram Mode
-
-Start the gateway and chat with Yuri via your Telegram bot:
+| `*create` | Create a new project |
+| `*plan` | Start planning (runs in background, agents auto-chain) |
+| `*develop` | Start development (4 agents run autonomously) |
+| `*test` | Run smoke tests |
+| `*deploy` | Deploy the project |
+| `*status` | Show progress + cost tracking |
+| `*projects` | List all registered projects |
+| `*switch <name>` | Switch active project |
+| `*cancel` | Stop running phase |
+| `*resume` | Resume from last checkpoint |
+| `*change "{desc}"` | Handle requirement change |
+
+### Agent Interaction via Telegram
+
+When a planning agent asks a question (e.g., PM asking to confirm features), Yuri bridges it to Telegram:
 
-```bash
-# With token as CLI argument
-orchestrix-yuri serve --telegram-token "YOUR_BOT_TOKEN"
-
-# Or configure in ~/.yuri/config/channels.yaml first
-orchestrix-yuri serve
 ```
+Yuri: "📋 PM is asking:
+       Which features to include?
+       1. User auth  2. Dashboard  3. API
+       ↩️ Reply to this message to answer"
 
-#### Channel Configuration
-
-Edit `~/.yuri/config/channels.yaml`:
-
-```yaml
-server:
-  port: 7890
-
-channels:
-  telegram:
-    enabled: true
-    token: "YOUR_BOT_TOKEN"
-    mode: polling
-    owner_chat_id: ""  # Auto-bound on first /start
-
-engine:
-  skill: yuri
-  tmux_session: yuri-gateway
-  startup_timeout: 30000
-  poll_interval: 2000
-  timeout: 300000
-  autocompact_pct: 80
-  compact_every: 50
+You reply: "1 and 2, skip 3"   ← forwarded to PM agent
 ```
 
-#### First-time Telegram setup
-
-1. Start the gateway: `orchestrix-yuri serve --telegram-token "YOUR_TOKEN"`
-2. Open Telegram, find your bot, send `/start`
-3. The first user to send `/start` becomes the owner (all others are rejected)
-4. Send any message to interact with Yuri
+**Normal messages** (not reply-to) always go to Yuri directly.
 
 ## Architecture
 
-### Persistent tmux Engine
-
-The Telegram gateway runs Claude Code in a persistent tmux session (`yuri-gateway`), not as a one-shot subprocess. This means:
+### Gateway Engine (claude-sdk)
 
-- **MCP servers connect once** and stay connected across messages
-- **Conversation context is preserved** natively by Claude Code
-- **No cold-start per message** — only the first message incurs startup latency
+Each Telegram message is processed via `claude -p --output-format json`:
 
-State detection uses Claude Code's TUI indicators:
+- **First message**: `--system-prompt` injects Yuri persona (SKILL.md) + L1 memory + channel instructions
+- **Subsequent**: `--resume SESSION_ID` preserves conversation context
+- **Output**: Structured JSON with `result` (clean text), `session_id`, `total_cost_usd`
 
-| Symbol | State | Description |
-|--------|-------|-------------|
-| `○` | Idle | Waiting for input |
-| `●` | Processing | Generating a response |
-| `◐` | Approval | Permission prompt (auto-approved) |
-| `[Verb]ed for Ns` | Complete | Response finished (e.g. "Baked for 31s") |
+### Async Phase Orchestration
 
-### Context Management (3-layer)
+`*plan` and `*develop` run as **Node.js background tasks** (not inside a `claude -p` call):
 
-1. **CLAUDE.md persistence** — core instructions are written to project CLAUDE.md, which survives auto-compact
-2. **Early auto-compact** — `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80` triggers compaction at 80% (not the default 95%)
-3. **Proactive /compact** — every 50 messages, a `/compact` is sent to keep context lean
+```
+*plan → PhaseOrchestrator.startPlan() → instant reply
+         ↓
+  setInterval(30s) polls tmux agent → detects completion
+         ↓
+  starts next agent → proactive Telegram notification
+         ↓
+  user asks anything → normal Claude response (not blocked)
+```
 
-### Memory System
+tmux is used **only for multi-agent orchestration** (plan/develop), not for the gateway itself.
 
-Yuri maintains a four-layer global memory at `~/.yuri/`:
+### Memory System (4 layers)
 
 ```
-~/.yuri/
-├── self.yaml                # Yuri identity
-├── boss/
-│   ├── profile.yaml         # Boss profile
-│   └── preferences.yaml     # Boss preferences
-├── portfolio/
-│   ├── registry.yaml        # All projects (active/archived)
-│   ├── priorities.yaml      # Portfolio priorities
-│   └── relationships.yaml   # Project relationships
-├── focus.yaml               # Current focus & state
-├── config/
-│   └── channels.yaml        # Gateway channel config
-├── chat-history/            # JSONL per chat_id
-├── inbox.jsonl              # Observation signals
-└── wisdom/                  # Accumulated knowledge
+L1 Global (~/.yuri/)           — Yuri identity, boss profile, portfolio, focus
+L2 Project ({project}/.yuri/)  — Project identity, knowledge, decisions
+L3 Phase State (state/)        — Per-phase operational status
+L4 Events (timeline/)          — Append-only event history
 ```
 
-### tmux Sessions
+**Reflect Engine**: Signals detected from user messages (preferences, identity, priorities) are written to `inbox.jsonl`, then processed by `reflect.js` into the corresponding YAML files before each Claude call.
 
-| Session | Purpose | Windows |
-|---------|---------|---------|
-| `yuri-gateway` | Telegram channel gateway | 1 (Claude Code interactive) |
-| `op-{project}` | Planning phase | One per agent (Analyst, PM, UX, Architect, PO) |
-| `orchestrix-{repo-id}` | Development phase | 4 fixed (Architect, SM, Dev, QA) |
+### Context Management
+
+- `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80` triggers auto-compact at 80%
+- Proactive `/compact` every 50 messages
+- L1 hash tracking: when memory changes, a `[CONTEXT UPDATE]` prefix is injected into the next message
 
 ### File Structure
 
 ```
 orchestrix-yuri/
 ├── bin/
-│   ├── install.js           # CLI entry (install / serve / migrate)
-│   └── serve.js             # Gateway launcher
+│   ├── install.js              # CLI entry (install/start/stop/status)
+│   ├── serve.js                # Gateway launcher
+│   ├── stop.js                 # PID-based stop
+│   └── status.js               # Gateway + cost status
 ├── lib/
-│   ├── installer.js         # Global install logic
-│   ├── migrate.js           # v1 → v2 memory migration
+│   ├── installer.js            # Global install logic
+│   ├── migrate.js              # v1 → v2 memory migration
 │   └── gateway/
-│       ├── index.js          # startGateway()
-│       ├── config.js         # Config loading + defaults
-│       ├── router.js         # Message routing + 5-engine orchestration
-│       ├── binding.js        # Owner authentication
-│       ├── history.js        # Chat history (JSONL)
+│       ├── index.js             # startGateway()
+│       ├── config.js            # Config loading + defaults
+│       ├── router.js            # Message routing, phase detection, signal detection
+│       ├── binding.js           # Owner authentication
+│       ├── history.js           # Chat history (JSONL)
+│       ├── log.js               # Colored terminal logging
 │       ├── channels/
-│       │   └── telegram.js   # grammy Telegram adapter
+│       │   └── telegram.js      # grammy adapter (placeholder + edit pattern)
 │       └── engine/
-│           └── claude-tmux.js # Persistent tmux session engine
+│           ├── claude-sdk.js    # Claude -p JSON engine + session management
+│           ├── phase-orchestrator.js  # Background plan/develop execution
+│           ├── reflect.js       # Inbox signal processing → YAML memory
+│           └── tmux-utils.js    # Shared tmux operations
 └── skill/
-    ├── SKILL.md              # Agent persona
-    ├── tasks/                # Phase workflow instructions
-    ├── scripts/              # Shell scripts (tmux, monitoring)
-    ├── templates/            # Memory schema
-    ├── data/                 # Decision rules
-    └── resources/            # MCP config, hooks, tmux scripts
+    ├── SKILL.md                 # Yuri persona + tmux command rules
+    ├── tasks/                   # Phase workflow instructions
+    ├── scripts/                 # Shell scripts (tmux, monitoring)
+    ├── templates/               # Memory schema
+    ├── data/                    # Decision rules, signal taxonomy
+    └── resources/               # MCP config, hooks, tmux scripts
 ```
 
-## Change Management
+### tmux Sessions (for agent orchestration)
+
+| Session | Purpose | Windows |
+|---------|---------|---------|
+| `op-{project}` | Planning phase | One per agent |
+| `orchestrix-{repo-id}` | Development phase | 4 fixed (Architect, SM, Dev, QA) |
 
-Yuri handles mid-project changes based on scope:
+## Change Management
 
 | Scope | Action |
 |-------|--------|
 | Small (≤5 files) | Dev `*solo` directly |
 | Medium | PO `*route-change` → standard workflow |
 | Large | Pause dev, partial re-plan |
-| New iteration | PM `*start-iteration` → parse next-steps.md → drive agents → resume dev |
-
-## Deployment Options
-
-| Region | Provider | Best For |
-|--------|----------|----------|
-| China | Sealos | Prototype / MVP |
-| China | Aliyun ECS + Docker | Production |
-| China | Vercel (CN) | Frontend / SSR |
-| Overseas | Vercel | Frontend / Full-stack |
-| Overseas | Railway | Backend APIs |
-| Overseas | AWS / GCP | Enterprise |
+| New iteration | PM `*start-iteration` → plan → dev → test |
 
 ## Troubleshooting
 
@@ -243,17 +208,23 @@ Yuri handles mid-project changes based on scope:
 # Check prerequisites
 tmux -V && which claude && node -v
 
-# View gateway logs (all output goes to stdout)
-orchestrix-yuri serve --telegram-token "..." 2>&1 | tee gateway.log
+# View gateway logs
+orchestrix-yuri start 2>&1 | tee gateway.log
+
+# Check status + cost
+orchestrix-yuri status
+
+# Stop the gateway
+orchestrix-yuri stop
 
-# Check if tmux session is alive
+# Check running tmux sessions (plan/develop phases)
 tmux ls
 
-# Peek into the Claude Code session
-tmux attach -t yuri-gateway
+# Peek into a planning agent
+tmux attach -t op-myproject
 
-# Manual cleanup if session gets stuck
-tmux kill-session -t yuri-gateway
+# Peek into dev agents
+tmux attach -t orchestrix-myproject
 ```
 
 ## License

package/bin/doctor.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const HOME = os.homedir();
+const YURI_GLOBAL = path.join(HOME, '.yuri');
+const SKILL_DIR = path.join(HOME, '.claude', 'skills', 'yuri');
+
+const c = {
+  reset: '\x1b[0m', green: '\x1b[32m', red: '\x1b[31m',
+  yellow: '\x1b[33m', cyan: '\x1b[36m', dim: '\x1b[90m', bold: '\x1b[1m',
+};
+
+let passCount = 0;
+let failCount = 0;
+let warnCount = 0;
+
+function pass(msg) { passCount++; console.log(`  ${c.green}✅${c.reset} ${msg}`); }
+function fail(msg, fix) {
+  failCount++;
+  console.log(`  ${c.red}❌${c.reset} ${msg}`);
+  if (fix) console.log(`     ${c.dim}Fix: ${fix}${c.reset}`);
+}
+function warn(msg) { warnCount++; console.log(`  ${c.yellow}⚠️${c.reset}  ${msg}`); }
+function info(msg) { console.log(`  ${c.dim}ℹ  ${msg}${c.reset}`); }
+function section(title) { console.log(`\n  ${c.bold}${c.cyan}${title}${c.reset}`); }
+
+function cmd(command) {
+  try { return execSync(command, { encoding: 'utf8', timeout: 10000 }).trim(); } catch { return null; }
+}
+
+function fileExists(p) { return fs.existsSync(p); }
+function isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+// ── Checks ─────────────────────────────────────────────────────────────────────
+
+function checkRuntime() {
+  section('1. Runtime Environment');
+
+  // Node.js
+  const nodeV = cmd('node --version');
+  if (nodeV) {
+    const major = parseInt(nodeV.replace('v', ''), 10);
+    if (major >= 18) pass(`Node.js ${nodeV}`);
+    else fail(`Node.js ${nodeV} (requires >= 18)`, 'Upgrade Node.js to v18+');
+  } else {
+    fail('Node.js not found', 'Install Node.js >= 18');
+  }
+
+  // tmux
+  const tmuxV = cmd('tmux -V');
+  if (tmuxV) pass(`tmux ${tmuxV}`);
+  else fail('tmux not found', 'brew install tmux (macOS) or apt install tmux (Linux)');
+
+  // zsh (needed for claude binary resolution)
+  const zshV = cmd('zsh --version');
+  if (zshV) pass(`zsh available`);
+  else warn('zsh not found — Claude binary resolution may fail on some systems');
+
+  // git
+  const gitV = cmd('git --version');
+  if (gitV) pass(`git available`);
+  else warn('git not found — project creation requires git');
+}
+
+function checkClaude() {
+  section('2. Claude Code CLI');
+
+  const candidates = [
+    cmd('zsh -lc "which claude" 2>/dev/null'),
+    '/usr/local/bin/claude',
+    '/opt/homebrew/bin/claude',
+    path.join(HOME, '.npm-global', 'bin', 'claude'),
+    path.join(HOME, '.local', 'bin', 'claude'),
+    path.join(HOME, '.claude', 'bin', 'claude'),
+  ].filter(Boolean);
+
+  let found = null;
+  for (const p of candidates) {
+    if (fileExists(p)) { found = p; break; }
+  }
+
+  if (found) {
+    pass(`Claude binary: ${found}`);
+    const version = cmd(`"${found}" --version 2>/dev/null`);
+    if (version) pass(`Claude Code ${version}`);
+    else warn('Could not get Claude Code version');
+  } else {
+    fail('Claude Code CLI not found', 'npm install -g @anthropic-ai/claude-code');
+  }
+}
+
+function checkInstallation() {
+  section('3. Yuri Installation');
+
+  // Skill files
+  const skillMd = path.join(SKILL_DIR, 'SKILL.md');
+  if (fileExists(skillMd)) {
+    const size = fs.statSync(skillMd).size;
+    if (size > 100) pass(`SKILL.md (${(size / 1024).toFixed(1)}KB)`);
+    else warn('SKILL.md exists but seems empty');
+  } else {
+    fail('SKILL.md not found', 'orchestrix-yuri install');
+  }
+
+  // Scripts
+  const scripts = ['ensure-session.sh', 'monitor-agent.sh', 'scan-stories.sh', 'start-planning.sh'];
+  const scriptDir = path.join(SKILL_DIR, 'scripts');
+  for (const s of scripts) {
+    const p = path.join(scriptDir, s);
+    if (fileExists(p)) {
+      if (isExecutable(p)) pass(`scripts/${s}`);
+      else warn(`scripts/${s} exists but not executable`);
+    } else {
+      warn(`scripts/${s} missing`);
+    }
+  }
+
+  // Resources
+  const resources = ['start-orchestrix.sh', 'handoff-detector.sh', 'settings.local.json'];
+  const resDir = path.join(SKILL_DIR, 'resources');
+  for (const r of resources) {
+    const p = path.join(resDir, r);
+    if (fileExists(p)) pass(`resources/${r}`);
+    else warn(`resources/${r} missing`);
+  }
+}
+
+function checkMemory() {
+  section('4. Global Memory (~/.yuri/)');
+
+  if (!fileExists(YURI_GLOBAL)) {
+    fail('~/.yuri/ directory not found', 'orchestrix-yuri install');
+    return;
+  }
+  pass('~/.yuri/ directory exists');
+
+  const required = [
+    ['self.yaml', 'Yuri identity'],
+    ['boss/profile.yaml', 'Boss profile'],
+    ['boss/preferences.yaml', 'Boss preferences'],
+    ['portfolio/registry.yaml', 'Project registry'],
+    ['focus.yaml', 'Global focus'],
+    ['config/channels.yaml', 'Channel config'],
+  ];
+
+  for (const [rel, label] of required) {
+    const p = path.join(YURI_GLOBAL, rel);
+    if (fileExists(p)) pass(`${rel}`);
+    else fail(`${rel} missing (${label})`, 'orchestrix-yuri install');
+  }
+
+  // Check inbox
+  const inboxPath = path.join(YURI_GLOBAL, 'inbox.jsonl');
+  if (fileExists(inboxPath)) {
+    const content = fs.readFileSync(inboxPath, 'utf8').trim();
+    const lines = content ? content.split('\n').length : 0;
+    const unprocessed = content ? content.split('\n').filter((l) => l.includes('"processed":false')).length : 0;
+    pass(`inbox.jsonl (${lines} entries, ${unprocessed} unprocessed)`);
+  } else {
+    warn('inbox.jsonl not found');
+  }
+
+  // Check wisdom
+  const wisdomDir = path.join(YURI_GLOBAL, 'wisdom');
+  if (fileExists(wisdomDir)) pass('wisdom/ directory');
+  else warn('wisdom/ directory missing');
+
+  // Chat history
+  const historyDir = path.join(YURI_GLOBAL, 'chat-history');
+  if (fileExists(historyDir)) pass('chat-history/ directory');
+  else warn('chat-history/ directory missing');
+}
+
+function checkConfig() {
+  section('5. Gateway Configuration');
+
+  const configPath = path.join(YURI_GLOBAL, 'config', 'channels.yaml');
+  if (!fileExists(configPath)) {
+    fail('channels.yaml not found', 'orchestrix-yuri install');
+    return;
+  }
+
+  try {
+    const yaml = require('js-yaml');
+    const config = yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+
+    // Telegram
+    const tg = config.channels && config.channels.telegram;
+    if (tg && tg.enabled && tg.token) {
+      if (tg.token.includes(':')) pass(`Telegram token configured (${tg.token.slice(0, 8)}...)`);
+      else warn('Telegram token format looks invalid (expected BOT_ID:TOKEN)');
+    } else if (tg && tg.enabled && !tg.token) {
+      fail('Telegram enabled but token is empty', 'orchestrix-yuri start --token YOUR_TOKEN');
+    } else {
+      info('Telegram not enabled');
+    }
+
+    // Owner binding
+    if (tg && tg.owner_chat_id) {
+      pass(`Owner bound: chat ${tg.owner_chat_id}`);
+    } else {
+      info('No owner bound yet (will auto-bind on first /start)');
+    }
+
+    // Engine
+    const engine = config.engine || {};
+    info(`Timeout: ${(engine.timeout || 300000) / 1000}s, Compact every: ${engine.compact_every || 50} msgs`);
+
+  } catch (err) {
+    fail(`channels.yaml parse error: ${err.message}`);
+  }
+}
+
+function checkGatewayState() {
+  section('6. Gateway State');
+
+  // PID file
+  const pidPath = path.join(YURI_GLOBAL, 'gateway.pid');
+  if (fileExists(pidPath)) {
+    const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+    try {
+      process.kill(pid, 0);
+      pass(`Gateway running (PID ${pid})`);
+    } catch {
+      warn(`Stale PID file (process ${pid} not running)`);
+    }
+  } else {
+    info('Gateway not running');
+  }
+
+  // Session state
+  const sessionPath = path.join(YURI_GLOBAL, 'gateway-session.json');
+  if (fileExists(sessionPath)) {
+    try {
+      const s = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+      const age = Date.now() - new Date(s.savedAt).getTime();
+      const ageH = (age / 3600000).toFixed(1);
+      if (age < 24 * 3600000) {
+        pass(`Session: ${s.sessionId.slice(0, 8)}... (${s.messageCount || 0} msgs, ${ageH}h old, $${(s.totalCost || 0).toFixed(4)})`);
+      } else {
+        warn(`Session expired (${ageH}h old)`);
+      }
+    } catch {
+      warn('Session file corrupted');
+    }
+  } else {
+    info('No session state (will create on first message)');
+  }
+
+  // tmux sessions
+  const tmuxList = cmd('tmux list-sessions -F "#{session_name}" 2>/dev/null');
+  if (tmuxList) {
+    const sessions = tmuxList.split('\n').filter((s) => s.startsWith('op-') || s.startsWith('orchestrix-'));
+    if (sessions.length > 0) {
+      for (const s of sessions) {
+        info(`Active tmux session: ${s}`);
+      }
+    }
+  }
+}
+
+function checkProjects() {
+  section('7. Projects');
+
+  const registryPath = path.join(YURI_GLOBAL, 'portfolio', 'registry.yaml');
+  if (!fileExists(registryPath)) {
+    info('No project registry');
+    return;
+  }
+
+  try {
+    const yaml = require('js-yaml');
+    const registry = yaml.load(fs.readFileSync(registryPath, 'utf8')) || {};
+    const projects = registry.projects || [];
+
+    if (projects.length === 0) {
+      info('No projects registered. Use *create to create one.');
+      return;
+    }
+
+    for (const p of projects) {
+      const rootExists = p.root && fileExists(p.root);
+      const status = rootExists ? `${p.status || '?'} (Phase ${p.phase || '?'})` : 'root directory missing!';
+      if (rootExists) pass(`${p.name || p.id}: ${status}`);
+      else fail(`${p.name || p.id}: ${status}`);
+    }
+
+    // Active project
+    const focusPath = path.join(YURI_GLOBAL, 'focus.yaml');
+    if (fileExists(focusPath)) {
+      const focus = yaml.load(fs.readFileSync(focusPath, 'utf8')) || {};
+      if (focus.active_project) {
+        info(`Active project: ${focus.active_project}`);
+      }
+    }
+  } catch { /* ok */ }
+}
+
+function checkNetwork() {
+  section('8. Network');
+
+  // Telegram API
+  const configPath = path.join(YURI_GLOBAL, 'config', 'channels.yaml');
+  if (fileExists(configPath)) {
+    try {
+      const yaml = require('js-yaml');
+      const config = yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+      const tg = config.channels && config.channels.telegram;
+
+      if (tg && tg.enabled && tg.token) {
+        const result = cmd(`curl -s -o /dev/null -w "%{http_code}" "https://api.telegram.org/bot${tg.token}/getMe" 2>/dev/null`);
+        if (result === '200') pass('Telegram API reachable + token valid');
+        else if (result === '401') fail('Telegram token is invalid (401)', 'Check your bot token with @BotFather');
+        else if (result) warn(`Telegram API returned HTTP ${result}`);
+        else warn('Cannot reach api.telegram.org (network issue?)');
+      }
+    } catch { /* ok */ }
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────────
+
+function doctor() {
+  console.log(`\n  ${c.bold}Orchestrix Yuri — Health Check${c.reset}\n`);
+
+  checkRuntime();
+  checkClaude();
+  checkInstallation();
+  checkMemory();
+  checkConfig();
+  checkGatewayState();
+  checkProjects();
+  checkNetwork();
+
+  // Summary
+  console.log(`\n  ${c.bold}Summary${c.reset}`);
+  console.log(`  ${c.green}✅ ${passCount} passed${c.reset}  ${failCount > 0 ? c.red : c.dim}❌ ${failCount} failed${c.reset}  ${warnCount > 0 ? c.yellow : c.dim}⚠️  ${warnCount} warnings${c.reset}`);
+
+  if (failCount === 0) {
+    console.log(`\n  ${c.green}${c.bold}All critical checks passed!${c.reset}\n`);
+  } else {
+    console.log(`\n  ${c.red}${failCount} issue(s) need attention. Fix them and run doctor again.${c.reset}\n`);
+  }
+
+  process.exit(failCount > 0 ? 1 : 0);
+}
+
+doctor();

package/bin/install.js

@@ -18,6 +18,8 @@ if (command === 'install') {
   require('./stop');
 } else if (command === 'status') {
   require('./status');
+} else if (command === 'doctor') {
+  require('./doctor');
 } else if (command === '--version' || command === '-v' || command === '-V') {
   const { version } = require('../package.json');
   console.log(version);
@@ -31,6 +33,7 @@ if (command === 'install') {
     orchestrix-yuri start --token TOKEN        Start & save Telegram Bot token (first time only)
     orchestrix-yuri stop                       Stop the running gateway
     orchestrix-yuri status                     Show gateway status
+    orchestrix-yuri doctor                     Health check all dependencies & config
     orchestrix-yuri migrate [path]             Migrate legacy memory.yaml
     orchestrix-yuri --version                  Show version
     orchestrix-yuri --help                     Show this help message

package/bin/status.js

@@ -30,6 +30,9 @@ function status() {
       const age = Date.now() - new Date(s.savedAt).getTime();
       if (age < 24 * 3600_000) {
         sessionInfo = `${s.sessionId.slice(0, 8)}... (${s.messageCount || 0} messages)`;
+        if (s.totalCost) {
+          sessionInfo += ` | $${s.totalCost.toFixed(4)}`;
+        }
       } else {
         sessionInfo = 'expired';
       }

package/lib/gateway/channels/telegram.js

@@ -39,16 +39,32 @@ class TelegramAdapter {
       };
 
       try {
+        // Send placeholder immediately so user sees instant feedback
+        const placeholder = await ctx.reply('...').catch(() => null);
+
         const reply = await this.onMessage(msg);
         if (reply && reply.text) {
-          // Telegram has a 4096 char limit per message
           const chunks = splitMessage(reply.text, 4000);
-          for (const chunk of chunks) {
-            await ctx.reply(chunk, { parse_mode: 'Markdown' }).catch(() => {
-              // Fallback: send without markdown if parsing fails
-              return ctx.reply(chunk);
+
+          if (placeholder && chunks.length === 1) {
+            // Single chunk: edit the placeholder message in-place
+            await ctx.api.editMessageText(ctx.chat.id, placeholder.message_id, chunks[0], { parse_mode: 'Markdown' }).catch(() => {
+              return ctx.api.editMessageText(ctx.chat.id, placeholder.message_id, chunks[0]).catch(() => {});
             });
+          } else {
+            // Multi-chunk: delete placeholder, send chunks separately
+            if (placeholder) {
+              await ctx.api.deleteMessage(ctx.chat.id, placeholder.message_id).catch(() => {});
+            }
+            for (const chunk of chunks) {
+              await ctx.reply(chunk, { parse_mode: 'Markdown' }).catch(() => {
+                return ctx.reply(chunk);
+              });
+            }
           }
+        } else if (placeholder) {
+          // No reply: remove placeholder
+          await ctx.api.deleteMessage(ctx.chat.id, placeholder.message_id).catch(() => {});
         }
       } catch (err) {
         log.error(`Message handling failed: ${err.message}`);

package/lib/gateway/engine/claude-sdk.js

@@ -117,6 +117,8 @@ let _sessionId = null;
 let _messageCount = 0;
 let _messageQueue = Promise.resolve();
 let _lastL1Hash = null;
+let _totalCost = 0;
+let _totalDuration = 0;
 
 // ── System Prompt ──────────────────────────────────────────────────────────────
 
@@ -188,6 +190,8 @@ function saveSessionState() {
       version: SESSION_VERSION,
       sessionId: _sessionId,
       messageCount: _messageCount,
+      totalCost: _totalCost,
+      totalDuration: _totalDuration,
       savedAt: new Date().toISOString(),
     }));
   } catch { /* best effort */ }
@@ -290,6 +294,8 @@ async function callClaude(opts) {
             log.engine(`Restoring session ${saved.sessionId.slice(0, 8)}...`);
             _sessionId = saved.sessionId;
             _messageCount = saved.messageCount || 0;
+            _totalCost = saved.totalCost || 0;
+            _totalDuration = saved.totalDuration || 0;
           }
         }
 
@@ -326,6 +332,8 @@ async function callClaude(opts) {
         }
 
         _messageCount++;
+        if (result.cost) _totalCost += result.cost;
+        if (result.duration) _totalDuration += result.duration;
         saveSessionState();
 
         // If --resume failed (session expired), retry with fresh session
@@ -385,10 +393,20 @@ function composePrompt(userMessage) {
  * Destroy session state. Called on gateway shutdown.
  */
 function destroySession() {
-  // Don't clear session file — allow restart to resume
   log.engine('Gateway shutting down (session preserved for restart)');
 }
 
+/**
+ * Get accumulated cost and usage stats.
+ */
+function getUsageStats() {
+  return {
+    messageCount: _messageCount,
+    totalCost: _totalCost,
+    totalDuration: _totalDuration,
+  };
+}
+
 module.exports = {
   callClaude,
   composePrompt,
@@ -396,4 +414,8 @@ module.exports = {
   resolveProjectRoot,
   findClaudeBinary,
   destroySession,
+  clearSessionState,
+  getUsageStats,
+  // Exported for testing
+  isEmptyTemplate,
 };

package/lib/gateway/router.js

@@ -24,6 +24,11 @@ const PHASE_COMMANDS = {
   cancel:  /^\*cancel\b/i,
 };
 
+const META_COMMANDS = {
+  projects: /^\*projects\b/i,
+  switch:   /^\*switch\s+(.+)/i,
+};
+
 const STATUS_PATTERNS = [
   /^\*status\b/i,
   /进度|状态|怎么样了|到哪了/,
@@ -128,6 +133,15 @@ class Router {
       return this._handleStatusQuery(msg);
     }
 
+    // ═══ META COMMANDS — *projects, *switch (always allowed) ═══
+    if (META_COMMANDS.projects.test(msg.text.trim())) {
+      return this._handleProjects(msg);
+    }
+    const switchMatch = msg.text.trim().match(META_COMMANDS.switch);
+    if (switchMatch) {
+      return this._handleSwitch(switchMatch[1].trim(), msg);
+    }
+
     // ═══ AGENT REPLY — user replied to an agent question notification ═══
     if (msg.replyToMessageId && this.orchestrator.isWaitingForInput()) {
       const waitingId = this.orchestrator.getWaitingMessageId();
@@ -252,8 +266,14 @@ class Router {
       }
     }
 
+    // Cost tracking
+    const usage = engine.getUsageStats();
+    if (usage.totalCost > 0) {
+      parts.push(`\n💰 Cost: $${usage.totalCost.toFixed(4)} | ${usage.messageCount} messages | ${(usage.totalDuration / 1000).toFixed(0)}s total`);
+    }
+
     if (parts.length === 0) {
-      parts.push('No active phase. Available commands: *create, *plan, *develop, *test, *deploy');
+      parts.push('No active phase. Available commands: *create, *plan, *develop, *test, *deploy, *projects, *switch');
     }
 
     this.history.append(msg.chatId, 'user', msg.text);
@@ -434,6 +454,80 @@ class Router {
     }
   }
 
+  // ── Multi-Project Commands ────────────────────────────────────────────────────
+
+  _handleProjects(msg) {
+    const registryPath = path.join(YURI_GLOBAL, 'portfolio', 'registry.yaml');
+    if (!fs.existsSync(registryPath)) {
+      return { text: 'No projects registered yet. Use *create to create one.' };
+    }
+
+    const registry = yaml.load(fs.readFileSync(registryPath, 'utf8')) || {};
+    const projects = registry.projects || [];
+    if (projects.length === 0) {
+      return { text: 'No projects registered yet. Use *create to create one.' };
+    }
+
+    // Read active project
+    const focusPath = path.join(YURI_GLOBAL, 'focus.yaml');
+    let activeId = '';
+    if (fs.existsSync(focusPath)) {
+      const focus = yaml.load(fs.readFileSync(focusPath, 'utf8')) || {};
+      activeId = focus.active_project || '';
+    }
+
+    const statusIcons = { active: '✅', paused: '💤', maintenance: '🔧', archived: '📦' };
+    const lines = projects.map((p, i) => {
+      const icon = statusIcons[p.status] || '❓';
+      const isCurrent = p.id === activeId ? ' ← current' : '';
+      return `${i + 1}. **${p.name || p.id}** ${icon} ${p.status} (Phase ${p.phase || '?'}: ${p.pulse || '?'})${isCurrent}`;
+    });
+
+    const reply = `📂 **Projects**\n\n${lines.join('\n')}\n\nUse \`*switch <name>\` to change active project.`;
+    this.history.append(msg.chatId, 'user', msg.text);
+    this.history.append(msg.chatId, 'assistant', reply);
+    return { text: reply };
+  }
+
+  _handleSwitch(query, msg) {
+    const registryPath = path.join(YURI_GLOBAL, 'portfolio', 'registry.yaml');
+    if (!fs.existsSync(registryPath)) {
+      return { text: '❌ No projects registered.' };
+    }
+
+    const registry = yaml.load(fs.readFileSync(registryPath, 'utf8')) || {};
+    const projects = registry.projects || [];
+    const q = query.toLowerCase();
+
+    // Fuzzy match: exact id, exact name, prefix of id, prefix of name
+    const match = projects.find((p) => p.id === q || (p.name && p.name.toLowerCase() === q))
+      || projects.find((p) => p.id.startsWith(q) || (p.name && p.name.toLowerCase().startsWith(q)));
+
+    if (!match) {
+      return { text: `❌ No project matching "${query}". Use *projects to see available projects.` };
+    }
+
+    // Update focus
+    const focusPath = path.join(YURI_GLOBAL, 'focus.yaml');
+    let focus = {};
+    if (fs.existsSync(focusPath)) {
+      focus = yaml.load(fs.readFileSync(focusPath, 'utf8')) || {};
+    }
+    focus.active_project = match.id;
+    focus.active_action = `switched to project: ${match.name || match.id}`;
+    focus.updated_at = new Date().toISOString();
+    fs.writeFileSync(focusPath, yaml.dump(focus, { lineWidth: -1 }));
+
+    // Clear Claude session so next message gets fresh system prompt for new project
+    engine.clearSessionState();
+
+    const reply = `✅ Switched to **${match.name || match.id}** (Phase ${match.phase || '?'}: ${match.pulse || '?'})`;
+    this.history.append(msg.chatId, 'user', msg.text);
+    this.history.append(msg.chatId, 'assistant', reply);
+    log.router(`Project switched to: ${match.id}`);
+    return { text: reply };
+  }
+
   _updateGlobalFocus(msg, projectRoot) {
     const focusPath = path.join(YURI_GLOBAL, 'focus.yaml');
     if (!fs.existsSync(focusPath)) return;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "orchestrix-yuri",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "Yuri — Meta-Orchestrator for Orchestrix. Drive your entire project lifecycle with natural language.",
   "main": "lib/installer.js",
   "bin": {
     "orchestrix-yuri": "bin/install.js"
   },
   "scripts": {
-    "test": "echo \"No tests yet\" && exit 0",
+    "test": "node --test 'test/*.test.js'",
     "serve": "node bin/serve.js"
   },
   "keywords": [