orchestrix-yuri 3.3.0 → 3.4.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/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/engine/phase-orchestrator.js

@@ -112,6 +112,43 @@ class PhaseOrchestrator {
     }
   }
 
+  /**
+   * Capture the current agent's tmux pane content for Claude context injection.
+   * Returns a formatted string or null if no agent is active.
+   */
+  captureCurrentAgentContext() {
+    if (!this._phase || !this._session || !tmx.hasSession(this._session)) {
+      return null;
+    }
+
+    if (this._phase === 'plan') {
+      const agent = PLAN_AGENTS[this._step];
+      if (!agent) return null;
+
+      const pane = tmx.capturePane(this._session, agent.window, 40);
+      if (!pane.trim()) return null;
+
+      const waiting = this._waitingForInput ? ' (WAITING FOR YOUR INPUT)' : '';
+      return `[LIVE AGENT CONTEXT] Phase: plan, Agent: ${agent.name} (${this._step + 1}/${PLAN_AGENTS.length})${waiting}\n` +
+             `tmux session: ${this._session}, window: ${agent.window}\n` +
+             `--- Agent output (last 40 lines) ---\n${pane}\n--- End agent output ---`;
+    }
+
+    if (this._phase === 'develop') {
+      // Capture all 4 dev windows briefly
+      const windows = ['Architect', 'SM', 'Dev', 'QA'];
+      const summaries = [];
+      for (let w = 0; w < 4; w++) {
+        const tail = tmx.capturePane(this._session, w, 5);
+        const lastLine = tail.split('\n').filter((l) => l.trim()).pop() || '(empty)';
+        summaries.push(`  Window ${w} (${windows[w]}): ${lastLine.trim().slice(0, 80)}`);
+      }
+      return `[LIVE AGENT CONTEXT] Phase: develop, Session: ${this._session}\n${summaries.join('\n')}`;
+    }
+
+    return null;
+  }
+
   getStatus() {
     if (!this._phase) {
       return { phase: null, message: 'No phase is running.' };

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);
@@ -270,7 +290,15 @@ class Router {
     await this._runCatchUp();
 
     const projectRoot = engine.resolveProjectRoot();
-    const prompt = engine.composePrompt(msg.text);
+
+    // If a phase is running, inject tmux pane context so Claude can see agent state
+    let prompt = engine.composePrompt(msg.text);
+    if (this.orchestrator.isRunning()) {
+      const agentContext = this.orchestrator.captureCurrentAgentContext();
+      if (agentContext) {
+        prompt = `${agentContext}\n\n---\n\nUser message: ${msg.text}`;
+      }
+    }
 
     log.router(`Processing: "${msg.text.slice(0, 80)}..." → cwd: ${projectRoot || '~'}`);
     const result = await engine.callClaude({
@@ -426,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.0",
+  "version": "3.4.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": [