instar 0.3.5 → 0.3.7

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

@@ -262,7 +262,95 @@ For **Project Agents**: Telegram is strongly recommended but optional. The agent
 
 If the user declines, that's their choice — but make the tradeoff clear in one sentence.
 
-Walk through setup step by step:
+#### Browser-Automated Setup (Default)
+
+**You have Playwright browser automation available.** Use it to do ALL of this for the user. They just need to be logged into Telegram Web.
+
+Tell the user:
+> "I'll set up Telegram for you automatically using the browser. Just make sure you're logged into web.telegram.org. I'll handle the bot creation, group setup, and everything else."
+
+Then ask:
+> "Are you logged into web.telegram.org?"
+
+If yes, proceed with full browser automation. If no, tell them to log in first and wait.
+
+**The automated flow:**
+
+1. **Navigate to web.telegram.org** using Playwright:
+   ```
+   mcp__playwright__browser_navigate({ url: "https://web.telegram.org/a/" })
+   ```
+   Take a snapshot to verify the user is logged in (look for the chat list, search bar, etc.). If you see a login/QR code screen, tell the user they need to log in first and wait.
+
+2. **Create a bot via @BotFather**:
+   - Take a snapshot, find the search input, click it
+   - Type "BotFather" in the search bar
+   - Take a snapshot, find @BotFather in the results, click it
+   - Take a snapshot, find the message input area
+   - If you see a "Start" button, click it. Otherwise type `/start` and press Enter
+   - Wait 2 seconds for BotFather to respond
+   - Type `/newbot` and press Enter
+   - Wait 2 seconds for BotFather to ask for a name
+   - Type the bot display name (use the project name, e.g., "My Project Agent") and press Enter
+   - Wait 2 seconds for BotFather to ask for a username
+   - Type the bot username (e.g., `myproject_agent_bot` — must end in "bot", use lowercase + underscores) and press Enter
+   - Wait 3 seconds for BotFather to respond with the token
+   - Take a snapshot and extract the bot token from BotFather's response. The token looks like `7123456789:AAHn3-xYz_example`. Look for text containing a colon between a number and alphanumeric characters.
+   - **CRITICAL: Store the token** — you'll need it for config.json
+
+3. **Create a group**:
+   - Take a snapshot of the main Telegram screen
+   - Find and click the "New Message" / compose / pencil button (usually bottom-left area of chat list)
+   - Take a snapshot, find "New Group" option, click it
+   - In the "Add Members" search, type the bot username you just created
+   - Take a snapshot, find the bot in results, click to select it
+   - Find and click the "Next" / arrow button to proceed
+   - Type the group name (use the project name, e.g., "My Project")
+   - Find and click "Create" / checkmark button
+   - Wait 2 seconds for the group to be created
+
+4. **Enable Topics**:
+   - Take a snapshot of the new group chat
+   - Click on the group name/header at the top to open group info
+   - Take a snapshot, find the Edit / pencil button, click it
+   - Take a snapshot, look for "Topics" toggle and enable it
+   - If you don't see Topics directly, look for "Group Type" or "Chat Type" first — changing this may reveal the Topics toggle
+   - Find and click Save / checkmark
+   - Wait 2 seconds
+
+5. **Make bot admin**:
+   - Take a snapshot of the group info or edit screen
+   - Navigate to Administrators section (may need to click group name first, then Edit)
+   - Click "Add Admin" or "Add Administrator"
+   - Search for your bot username
+   - Take a snapshot, find the bot, click to select
+   - Click Save / Done to confirm admin rights
+   - Wait 2 seconds
+
+6. **Detect chat ID**:
+   - Type "hello" in the group chat and send it (this triggers the bot to see the group)
+   - Wait 3 seconds for the message to propagate to the bot
+   - Use Bash to call the Telegram Bot API:
+   ```bash
+   curl -s "https://api.telegram.org/bot${TOKEN}/getUpdates?offset=-1" > /dev/null
+   curl -s "https://api.telegram.org/bot${TOKEN}/getUpdates?timeout=5"
+   ```
+   - Parse the response to find `chat.id` where `chat.type` is "supergroup" or "group"
+   - If auto-detection fails, try once more (send another message, wait, call API again)
+
+**Browser automation tips:**
+- **Always take a snapshot** before interacting. Telegram Web's UI changes frequently.
+- **Use `mcp__playwright__browser_snapshot`** to see the accessibility tree (more reliable than screenshots for finding elements).
+- **Use `mcp__playwright__browser_click`** with element refs from the snapshot.
+- **Use `mcp__playwright__browser_type`** to type text into inputs. For the Telegram message input, you may need to find the message input ref and use `submit: true` to send.
+- **Wait 2-3 seconds** after each action for Telegram to process. Use `mcp__playwright__browser_wait_for({ time: 2 })`.
+- **If an element isn't found**, take a fresh snapshot — Telegram may have changed the view.
+- **Telegram Web uses version "a"** (web.telegram.org/a/) — this is the React-based client.
+- **If something goes wrong**, tell the user what happened and offer to retry that step or fall back to manual instructions.
+
+#### Manual Fallback
+
+If Playwright tools are not available, or if browser automation fails, fall back to the manual walkthrough:
 
 1. **Create a bot** via @BotFather on Telegram:
    - Open https://web.telegram.org
@@ -276,7 +364,6 @@ Walk through setup step by step:
 
 3. **Enable Topics**:
    - Open group info, Edit, turn on Topics
-   - This gives you separate threads (like Slack channels)
 
 4. **Make bot admin**:
    - Group info, Edit, Administrators, Add your bot

package/dist/commands/init.d.ts

@@ -42,7 +42,8 @@ export declare function initProject(options: InitOptions): Promise<void>;
  * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
  * Called after updates to ensure new hooks and documentation are installed.
  * Re-writes all hook files (idempotent), merges new hooks into settings,
- * and appends any missing sections to CLAUDE.md.
+ * appends any missing sections to CLAUDE.md, and installs scripts for
+ * configured integrations (e.g., Telegram relay).
  */
 export declare function refreshHooksAndSettings(projectDir: string, stateDir: string): void;
 export {};

package/dist/commands/init.js

@@ -636,13 +636,15 @@ If everything looks healthy, exit silently. Only report issues.`,
  * Refresh hooks, Claude settings, and CLAUDE.md for an existing installation.
  * Called after updates to ensure new hooks and documentation are installed.
  * Re-writes all hook files (idempotent), merges new hooks into settings,
- * and appends any missing sections to CLAUDE.md.
+ * appends any missing sections to CLAUDE.md, and installs scripts for
+ * configured integrations (e.g., Telegram relay).
  */
 export function refreshHooksAndSettings(projectDir, stateDir) {
     installHooks(stateDir);
     installClaudeSettings(projectDir);
     refreshClaudeMd(projectDir, stateDir);
     refreshJobs(stateDir);
+    refreshScripts(projectDir, stateDir);
 }
 /**
  * Merge new default jobs into existing jobs.json without overwriting user changes.
@@ -675,21 +677,116 @@ function refreshJobs(stateDir) {
     }
     catch { /* don't break on errors */ }
 }
+/**
+ * Read config.json from state dir, returning parsed config or null.
+ */
+function readConfig(stateDir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if Telegram is configured in config.json.
+ */
+function isTelegramConfigured(stateDir) {
+    const config = readConfig(stateDir);
+    if (!config)
+        return false;
+    const messaging = config.messaging;
+    return !!messaging?.some(m => m.type === 'telegram' && m.enabled);
+}
+/**
+ * Install scripts for configured integrations (e.g., Telegram relay).
+ * Called during refresh to ensure scripts exist for all configured integrations.
+ */
+function refreshScripts(projectDir, stateDir) {
+    const config = readConfig(stateDir);
+    if (!config)
+        return;
+    const port = config.port || 4040;
+    // Install telegram-reply.sh if Telegram is configured
+    if (isTelegramConfigured(stateDir)) {
+        installTelegramRelay(projectDir, port);
+    }
+}
+/**
+ * Install the Telegram relay script that Claude uses to send responses
+ * back to Telegram topics via the instar server API.
+ */
+function installTelegramRelay(projectDir, port) {
+    const scriptsDir = path.join(projectDir, '.claude', 'scripts');
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    const scriptContent = `#!/bin/bash
+# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
+#
+# Usage:
+#   .claude/scripts/telegram-reply.sh TOPIC_ID "message text"
+#   echo "message text" | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   cat <<'EOF' | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   Multi-line message here
+#   EOF
+
+TOPIC_ID="$1"
+shift
+
+if [ -z "$TOPIC_ID" ]; then
+  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="\${INSTAR_PORT:-${port}}"
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  # Fallback if python3 not available: basic escape
+  JSON_MSG="$(printf '%s' "$MSG" | sed 's/\\\\\\\\/\\\\\\\\\\\\\\\\/g; s/"/\\\\\\\\"/g' | sed ':a;N;$!ba;s/\\\\n/\\\\\\\\n/g')"
+  JSON_MSG="\\"$JSON_MSG\\""
+fi
+
+RESPONSE=$(curl -s -w "\\n%{http_code}" -X POST "http://localhost:\${PORT}/telegram/reply/\${TOPIC_ID}" \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"text\\":\${JSON_MSG}}")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi
+`;
+    const scriptPath = path.join(scriptsDir, 'telegram-reply.sh');
+    fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
+}
 /**
  * Append missing sections to CLAUDE.md without overwriting user customizations.
  * Reads config.json for port, checks for known section headers, appends if missing.
+ * Also adds Telegram relay section if Telegram is configured.
  */
 function refreshClaudeMd(projectDir, stateDir) {
     const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
     if (!fs.existsSync(claudeMdPath))
         return;
-    // Read port from config
-    let port = 4321;
-    try {
-        const config = JSON.parse(fs.readFileSync(path.join(stateDir, 'config.json'), 'utf-8'));
-        port = config.port || 4321;
-    }
-    catch { /* use default port */ }
+    const config = readConfig(stateDir);
+    const port = config?.port || 4040;
     const content = fs.readFileSync(claudeMdPath, 'utf-8');
     const additions = [];
     // Check for Self-Diagnosis section
@@ -719,6 +816,22 @@ curl -s -X POST http://localhost:${port}/feedback \\
 Types: \`bug\`, \`feature\`, \`improvement\`, \`question\`
 
 **Do not wait for the user to notice.** If a hook throws an error, report it. If a job fails, report it. If the server returns unexpected data, report it. You are not just using instar — you are part of its immune system.
+`);
+    }
+    // Check for Telegram Relay section (add if Telegram is configured)
+    if (isTelegramConfigured(stateDir) && !content.includes('Telegram Relay')) {
+        additions.push(`
+## Telegram Relay
+
+When user input starts with \`[telegram:N]\`, the message came from a user via Telegram topic N. After responding, relay the response back:
+
+\`\`\`bash
+cat <<'EOF' | .claude/scripts/telegram-reply.sh N
+Your response text here
+EOF
+\`\`\`
+
+Strip the \`[telegram:N]\` prefix before interpreting the message. Only relay conversational text — not tool output.
 `);
     }
     if (additions.length > 0) {
@@ -1044,6 +1157,17 @@ function installClaudeSettings(projectDir) {
             },
         ];
     }
+    // MCP Servers: Playwright for browser automation (used by setup wizard, Telegram setup, etc.)
+    if (!settings.mcpServers) {
+        settings.mcpServers = {};
+    }
+    const mcpServers = settings.mcpServers;
+    if (!mcpServers.playwright) {
+        mcpServers.playwright = {
+            command: 'npx',
+            args: ['-y', '@playwright/mcp@latest'],
+        };
+    }
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 //# sourceMappingURL=init.js.map

package/dist/commands/server.js

@@ -50,20 +50,17 @@ async function respawnSessionForTopic(sessionManager, telegram, targetSession, t
     catch (err) {
         console.error(`[telegram→session] Failed to fetch thread history:`, err);
     }
-    // Always keep the user's message inline — never hide it behind a file reference.
-    // Only thread history goes into a file for supplementary context.
+    // Single-line bootstrap to avoid tmux send-keys newline issues.
+    // Thread history and context go into temp files for Claude to read.
+    const tmpDir = '/tmp/instar-telegram';
+    fs.mkdirSync(tmpDir, { recursive: true });
     let bootstrapMessage;
     if (historyLines.length > 0) {
         const historyContent = historyLines.join('\n');
-        const tmpDir = '/tmp/instar-telegram';
-        fs.mkdirSync(tmpDir, { recursive: true });
         const filepath = path.join(tmpDir, `history-${topicId}-${Date.now()}-${process.pid}.txt`);
         fs.writeFileSync(filepath, historyContent);
-        bootstrapMessage = [
-            `[telegram:${topicId}] ${msg}`,
-            ``,
-            `(Session was respawned. Thread history is at ${filepath} — read it for context. Then RESPOND to the user's message above via Telegram relay.)`,
-        ].join('\n');
+        // Single-line: user message + file reference for history
+        bootstrapMessage = `[telegram:${topicId}] ${msg} (Session respawned. Thread history at ${filepath} — read it for context before responding.)`;
     }
     else {
         bootstrapMessage = `[telegram:${topicId}] ${msg}`;
@@ -125,15 +122,22 @@ function wireTelegramRouting(telegram, sessionManager) {
             // No session mapped — auto-spawn one
             console.log(`[telegram→session] No session for topic ${topicId}, auto-spawning...`);
             const storedName = telegram.getTopicName(topicId) || `topic-${topicId}`;
-            // Always keep the user's message inline — never hide it behind a file reference
-            const bootstrapMessage = [
-                `[telegram:${topicId}] ${text}`,
-                ``,
-                `(This session was auto-created for a Telegram topic. Respond to the user's message above via Telegram relay.)`,
-            ].join('\n');
+            // Single-line bootstrap to avoid tmux send-keys newline issues.
+            // Multi-line context is written to a temp file for Claude to read.
+            const contextLines = [
+                `This session was auto-created for Telegram topic ${topicId}.`,
+                `Respond to the user's message via Telegram relay: cat <<'EOF' | .claude/scripts/telegram-reply.sh ${topicId}`,
+                `Your response here`,
+                `EOF`,
+            ];
+            const tmpDir = '/tmp/instar-telegram';
+            fs.mkdirSync(tmpDir, { recursive: true });
+            const ctxPath = path.join(tmpDir, `ctx-${topicId}-${Date.now()}.txt`);
+            fs.writeFileSync(ctxPath, contextLines.join('\n'));
+            const bootstrapMessage = `[telegram:${topicId}] ${text}`;
             sessionManager.spawnInteractiveSession(bootstrapMessage, storedName).then((newSessionName) => {
                 telegram.registerTopicSession(topicId, newSessionName);
-                telegram.sendToTopic(topicId, `Session auto-created. I'm here.`).catch(() => { });
+                telegram.sendToTopic(topicId, `Session created.`).catch(() => { });
                 console.log(`[telegram→session] Auto-spawned "${newSessionName}" for topic ${topicId}`);
             }).catch((err) => {
                 console.error(`[telegram→session] Auto-spawn failed:`, err);

package/dist/core/PostUpdateMigrator.d.ts

@@ -55,6 +55,11 @@ export declare class PostUpdateMigrator {
      * Never overwrites existing scripts (user may have customized them).
      */
     private migrateScripts;
+    /**
+     * Ensure .claude/settings.json has required MCP servers.
+     * Only adds — never removes existing configuration.
+     */
+    private migrateSettings;
     private getSessionStartHook;
     private getDangerousCommandGuard;
     private getGroundingBeforeMessaging;

package/dist/core/PostUpdateMigrator.js

@@ -37,6 +37,7 @@ export class PostUpdateMigrator {
         this.migrateHooks(result);
         this.migrateClaudeMd(result);
         this.migrateScripts(result);
+        this.migrateSettings(result);
         return result;
     }
     /**
@@ -191,6 +192,50 @@ Strip the \`[telegram:N]\` prefix before interpreting the message. Respond natur
             result.skipped.push('scripts/health-watchdog.sh (already exists)');
         }
     }
+    /**
+     * Ensure .claude/settings.json has required MCP servers.
+     * Only adds — never removes existing configuration.
+     */
+    migrateSettings(result) {
+        const settingsPath = path.join(this.config.projectDir, '.claude', 'settings.json');
+        if (!fs.existsSync(settingsPath)) {
+            result.skipped.push('.claude/settings.json (not found — will be created on next init)');
+            return;
+        }
+        let settings;
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        }
+        catch (err) {
+            result.errors.push(`settings.json read: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        let patched = false;
+        // Playwright MCP server — required for browser automation (Telegram setup, etc.)
+        if (!settings.mcpServers) {
+            settings.mcpServers = {};
+        }
+        const mcpServers = settings.mcpServers;
+        if (!mcpServers.playwright) {
+            mcpServers.playwright = {
+                command: 'npx',
+                args: ['-y', '@playwright/mcp@latest'],
+            };
+            patched = true;
+            result.upgraded.push('.claude/settings.json: added Playwright MCP server');
+        }
+        else {
+            result.skipped.push('.claude/settings.json: Playwright MCP already configured');
+        }
+        if (patched) {
+            try {
+                fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+            }
+            catch (err) {
+                result.errors.push(`settings.json write: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     // ── Hook Templates ─────────────────────────────────────────────────
     getSessionStartHook() {
         return `#!/bin/bash

package/dist/core/SessionManager.d.ts

@@ -88,11 +88,14 @@ export declare class SessionManager extends EventEmitter {
     injectTelegramMessage(tmuxSession: string, topicId: number, text: string): void;
     /**
      * Send text to a tmux session via send-keys.
-     * Uses -l (literal) flag for text, then sends Enter separately.
+     * For single-line text, uses -l (literal) flag directly.
+     * For multi-line text, writes to a temp file and uses tmux load-buffer/paste-buffer
+     * to avoid newlines being interpreted as Enter keypresses.
      */
     private injectMessage;
     /**
      * Wait for Claude to be ready in a tmux session by polling output.
+     * Looks for Claude Code's prompt character (❯) which appears when ready for input.
      */
     private waitForClaudeReady;
     private tmuxSessionExists;

package/dist/core/SessionManager.js

@@ -314,9 +314,15 @@ export class SessionManager extends EventEmitter {
             this.waitForClaudeReady(tmuxSession).then((ready) => {
                 if (ready) {
                     this.injectMessage(tmuxSession, initialMessage);
+                    console.log(`[SessionManager] Injected initial message into "${tmuxSession}" (${initialMessage.length} chars)`);
                 }
                 else {
-                    console.error(`[SessionManager] Claude not ready in session "${tmuxSession}" after timeout`);
+                    console.error(`[SessionManager] Claude not ready in session "${tmuxSession}" — message NOT injected. Session may need manual intervention.`);
+                    // Still try to inject — Claude might be ready but prompt detection failed
+                    if (this.tmuxSessionExists(tmuxSession)) {
+                        console.log(`[SessionManager] Session "${tmuxSession}" still alive — attempting injection anyway`);
+                        this.injectMessage(tmuxSession, initialMessage);
+                    }
                 }
             }).catch((err) => {
                 console.error(`[SessionManager] Error waiting for Claude ready in "${tmuxSession}": ${err}`);
@@ -346,19 +352,50 @@ export class SessionManager extends EventEmitter {
     }
     /**
      * Send text to a tmux session via send-keys.
-     * Uses -l (literal) flag for text, then sends Enter separately.
+     * For single-line text, uses -l (literal) flag directly.
+     * For multi-line text, writes to a temp file and uses tmux load-buffer/paste-buffer
+     * to avoid newlines being interpreted as Enter keypresses.
      */
     injectMessage(tmuxSession, text) {
         const exactTarget = `=${tmuxSession}:`;
         try {
-            // Send the text literally
-            execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, '-l', text], {
-                encoding: 'utf-8', timeout: 5000,
-            });
-            // Send Enter separately
-            execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
-                encoding: 'utf-8', timeout: 5000,
-            });
+            if (text.includes('\n')) {
+                // Multi-line: write to temp file, load into tmux buffer, paste into pane.
+                // This avoids newlines being treated as Enter keypresses which would
+                // fragment the message into multiple Claude prompts.
+                const tmpDir = path.join('/tmp', 'instar-inject');
+                fs.mkdirSync(tmpDir, { recursive: true });
+                const tmpPath = path.join(tmpDir, `msg-${Date.now()}-${process.pid}.txt`);
+                fs.writeFileSync(tmpPath, text);
+                try {
+                    execFileSync(this.config.tmuxPath, ['load-buffer', tmpPath], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                    execFileSync(this.config.tmuxPath, ['paste-buffer', '-t', exactTarget, '-p'], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                    // Send Enter to submit
+                    execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
+                        encoding: 'utf-8', timeout: 5000,
+                    });
+                }
+                finally {
+                    try {
+                        fs.unlinkSync(tmpPath);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            else {
+                // Single-line: simple send-keys
+                execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, '-l', text], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
+                // Send Enter separately
+                execFileSync(this.config.tmuxPath, ['send-keys', '-t', exactTarget, 'Enter'], {
+                    encoding: 'utf-8', timeout: 5000,
+                });
+            }
         }
         catch (err) {
             console.error(`[SessionManager] Failed to inject message into ${tmuxSession}: ${err}`);
@@ -366,20 +403,29 @@ export class SessionManager extends EventEmitter {
     }
     /**
      * Wait for Claude to be ready in a tmux session by polling output.
+     * Looks for Claude Code's prompt character (❯) which appears when ready for input.
      */
-    async waitForClaudeReady(tmuxSession, timeoutMs = 15000) {
+    async waitForClaudeReady(tmuxSession, timeoutMs = 30000) {
         const start = Date.now();
         // Wait a minimum startup delay before checking (Claude needs time to load)
-        await new Promise(r => setTimeout(r, 2000));
+        await new Promise(r => setTimeout(r, 3000));
         while (Date.now() - start < timeoutMs) {
+            if (!this.tmuxSessionExists(tmuxSession)) {
+                console.error(`[SessionManager] Session "${tmuxSession}" died during startup`);
+                return false;
+            }
             const output = this.captureOutput(tmuxSession, 10);
             // Check for Claude Code's specific prompt character (❯)
             // Avoid matching generic shell prompts (> and $) which cause false positives
             if (output && output.includes('❯')) {
+                console.log(`[SessionManager] Claude ready in "${tmuxSession}" after ${Date.now() - start}ms`);
                 return true;
             }
             await new Promise(r => setTimeout(r, 500));
         }
+        // Log what we see on timeout for debugging
+        const finalOutput = this.captureOutput(tmuxSession, 20);
+        console.error(`[SessionManager] Claude not ready in "${tmuxSession}" after ${timeoutMs}ms. Output: ${(finalOutput || '').slice(-200)}`);
         return false;
     }
     tmuxSessionExists(name) {

package/package.json

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