instar 0.4.8 → 0.4.9

package/dist/commands/init.js

@@ -825,7 +825,11 @@ Types: \`bug\`, \`feature\`, \`improvement\`, \`question\`
         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:
+When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N.
+
+**IMMEDIATE ACKNOWLEDGMENT (MANDATORY):** When you receive a Telegram message, your FIRST action — before reading files, searching code, or doing any work — must be sending a brief acknowledgment back. This confirms the message was received and you haven't stalled. Examples: "Got it, looking into this now." / "On it — checking the scheduler." / "Received, working on the sync." Then do the work, then send the full response.
+
+**Response relay:** After completing your work, relay your response back:
 
 \`\`\`bash
 cat <<'EOF' | .claude/scripts/telegram-reply.sh N
@@ -833,7 +837,7 @@ Your response text here
 EOF
 \`\`\`
 
-Strip the \`[telegram:N]\` prefix before interpreting the message. Only relay conversational text — not tool output.
+Strip the \`[telegram:N]\` prefix before interpreting the message. Respond naturally, then relay. Only relay your conversational text — not tool output or internal reasoning.
 `);
     }
     if (additions.length > 0) {

package/dist/commands/server.js

@@ -177,11 +177,14 @@ function wireTelegramRouting(telegram, sessionManager) {
             if (sessionManager.isSessionAlive(targetSession)) {
                 console.log(`[telegram→session] Injecting into ${targetSession}: "${text.slice(0, 80)}"`);
                 sessionManager.injectTelegramMessage(targetSession, topicId, text);
+                // Delivery confirmation — let the user know the message reached the session
+                telegram.sendToTopic(topicId, `✓ Delivered`).catch(() => { });
                 // Track for stall detection
                 telegram.trackMessageInjection(topicId, targetSession, text);
             }
             else {
                 // Session died — respawn with thread history
+                telegram.sendToTopic(topicId, `🔄 Session restarting — message queued.`).catch(() => { });
                 respawnSessionForTopic(sessionManager, telegram, targetSession, topicId, text).catch(err => {
                     console.error(`[telegram→session] Respawn failed:`, err);
                 });

package/dist/commands/setup.js

@@ -894,7 +894,11 @@ Every user's feedback makes the platform better for everyone. Report issues when
         section += `
 ## Telegram Relay
 
-When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N. **After responding**, relay your response back:
+When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N.
+
+**IMMEDIATE ACKNOWLEDGMENT (MANDATORY):** When you receive a Telegram message, your FIRST action — before reading files, searching code, or doing any work — must be sending a brief acknowledgment back. This confirms the message was received and you haven't stalled. Examples: "Got it, looking into this now." / "On it — checking the scheduler." / "Received, working on the sync." Then do the work, then send the full response.
+
+**Response relay:** After completing your work, relay your response back:
 
 \`\`\`bash
 cat <<'EOF' | .claude/scripts/telegram-reply.sh N

package/dist/core/PostUpdateMigrator.js

@@ -131,7 +131,11 @@ This returns your full capability matrix: scripts, hooks, Telegram status, jobs,
             const section = `
 ## Telegram Relay
 
-When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N. **After responding**, relay your response back:
+When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N.
+
+**IMMEDIATE ACKNOWLEDGMENT (MANDATORY):** When you receive a Telegram message, your FIRST action — before reading files, searching code, or doing any work — must be sending a brief acknowledgment back. This confirms the message was received and you haven't stalled. Examples: "Got it, looking into this now." / "On it — checking the scheduler." / "Received, working on the sync." Then do the work, then send the full response.
+
+**Response relay:** After completing your work, relay your response back:
 
 \`\`\`bash
 cat <<'EOF' | .claude/scripts/telegram-reply.sh N
@@ -145,6 +149,20 @@ Strip the \`[telegram:N]\` prefix before interpreting the message. Respond natur
             patched = true;
             result.upgraded.push('CLAUDE.md: added Telegram Relay section');
         }
+        // Upgrade existing Telegram Relay sections to include mandatory acknowledgment
+        if (this.config.hasTelegram && content.includes('Telegram Relay') && !content.includes('IMMEDIATE ACKNOWLEDGMENT')) {
+            const ackBlock = `\n**IMMEDIATE ACKNOWLEDGMENT (MANDATORY):** When you receive a Telegram message, your FIRST action — before reading files, searching code, or doing any work — must be sending a brief acknowledgment back. This confirms the message was received and you haven't stalled. Examples: "Got it, looking into this now." / "On it — checking the scheduler." / "Received, working on the sync." Then do the work, then send the full response.\n`;
+            // Insert after the first line of the Telegram Relay section
+            const relayIdx = content.indexOf('## Telegram Relay');
+            if (relayIdx >= 0) {
+                const nextNewline = content.indexOf('\n\n', relayIdx + 18);
+                if (nextNewline >= 0) {
+                    content = content.slice(0, nextNewline + 1) + ackBlock + content.slice(nextNewline + 1);
+                    patched = true;
+                    result.upgraded.push('CLAUDE.md: added mandatory acknowledgment to Telegram Relay');
+                }
+            }
+        }
         if (patched) {
             try {
                 fs.writeFileSync(claudeMdPath, content);

package/dist/core/SessionManager.d.ts

@@ -42,7 +42,8 @@ export declare class SessionManager extends EventEmitter {
         maxDurationMinutes?: number;
     }): Promise<Session>;
     /**
-     * Check if a session is still running by checking tmux (sync version).
+     * Check if a session is still running by checking tmux AND verifying
+     * that the Claude process is running inside (not a zombie tmux pane).
      */
     isSessionAlive(tmuxSession: string): boolean;
     /**

package/dist/core/SessionManager.js

@@ -142,10 +142,30 @@ export class SessionManager extends EventEmitter {
         return session;
     }
     /**
-     * Check if a session is still running by checking tmux (sync version).
+     * Check if a session is still running by checking tmux AND verifying
+     * that the Claude process is running inside (not a zombie tmux pane).
      */
     isSessionAlive(tmuxSession) {
-        return this.tmuxSessionExists(tmuxSession);
+        if (!this.tmuxSessionExists(tmuxSession))
+            return false;
+        // Verify Claude process is running inside the tmux session
+        try {
+            const paneCmd = execFileSync(this.config.tmuxPath, ['display-message', '-t', `=${tmuxSession}:`, '-p', '#{pane_current_command}'], { encoding: 'utf-8', timeout: 5000 }).trim();
+            // Claude Code runs as 'claude' or 'node' process
+            if (paneCmd && (paneCmd.includes('claude') || paneCmd.includes('node'))) {
+                return true;
+            }
+            // If pane command is bash/zsh/sh, Claude may have exited — session is dead
+            if (paneCmd === 'bash' || paneCmd === 'zsh' || paneCmd === 'sh') {
+                return false;
+            }
+            // For any other command, assume alive (could be a Claude subprocess)
+            return true;
+        }
+        catch {
+            // If we can't check, fall back to tmux session existence
+            return true;
+        }
     }
     /**
      * Check if a session is still running by checking tmux (async version).

package/dist/messaging/TelegramAdapter.js

@@ -502,6 +502,8 @@ export class TelegramAdapter {
             }
             try {
                 const success = await this.onInterruptSession(sessionName);
+                // Clear stall tracking — user is actively intervening
+                this.clearStallForTopic(topicId);
                 if (success) {
                     await this.sendToTopic(topicId, `Sent Escape to "${sessionName}" \u2014 it should resume processing.`).catch(() => { });
                 }
@@ -525,6 +527,8 @@ export class TelegramAdapter {
                 await this.sendToTopic(topicId, 'Restart not available (no handler registered).').catch(() => { });
                 return true;
             }
+            // Clear stall tracking — user is actively intervening
+            this.clearStallForTopic(topicId);
             await this.sendToTopic(topicId, `Restarting "${sessionName}"...`).catch(() => { });
             try {
                 await this.onRestartSession(sessionName, topicId);

package/dist/scaffold/templates.js

@@ -30,6 +30,7 @@ ${identity.personality}
 4. **Be honest about limits.** If I can't do something, I say so clearly. I don't fabricate experience or claim capabilities I don't have.
 5. **Infrastructure over improvisation.** If I solve a problem twice, I make it a script, a job, or a documented pattern.
 6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, and more. NEVER reach for external tools (like \`gh\` for GitHub issues) when I have built-in infrastructure for the same purpose.
+7. **Registry first, explore second.** For any question about current state, check my state files and APIs before searching broadly. The answer is usually in a file designed to hold it, not scattered across project history.
 
 ## Who I Work With
 
@@ -165,6 +166,31 @@ curl http://localhost:${port}/capabilities
 
 This returns your full capability matrix: scripts, hooks, Telegram status, jobs, relationships, and more. It is the source of truth about what you can do. **Never hallucinate about missing capabilities — verify first.**
 
+### Registry First, Explore Second
+
+**For ANY question about current state, check your state files BEFORE searching broadly.**
+
+I maintain registries that are the source of truth for specific categories. These MUST be checked before broad exploration:
+
+| Question | Check First |
+|----------|-------------|
+| What can I do? | \`curl http://localhost:${port}/capabilities\` |
+| Who do I work with? | \`.instar/USER.md\` |
+| What have I learned? | \`.instar/MEMORY.md\` |
+| What jobs do I have? | \`.instar/jobs.json\` or \`curl http://localhost:${port}/jobs\` |
+| Who have I interacted with? | \`curl http://localhost:${port}/relationships\` |
+| My configuration? | \`.instar/config.json\` |
+| My identity/principles? | \`.instar/AGENT.md\` |
+| Project architecture? | This file (CLAUDE.md), then project docs |
+
+**Why this matters:** Searching 1000 files to answer a question that a single state file could answer is slower AND less reliable. Broad searches find stale narratives. State files are current. This applies at EVERY level — including sub-agents I spawn. When spawning a research agent, include the relevant state file reference in its prompt so it searches WITH context, not blind.
+
+**The hierarchy when sources conflict:**
+1. State files and API endpoints — canonical, designed to be current
+2. MEMORY.md — accumulated learnings, periodically updated
+3. Project documentation — may be stale
+4. Broad search results — useful for discovery, unreliable for current state
+
 ### Building New Capabilities
 
 When asked for something I can't do yet, I build it:
@@ -221,6 +247,8 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"Settle for Failure"** — If a tool returns empty or fails, try alternatives before concluding something is impossible.
 
+**"Search Blind"** — Don't grep the entire project to answer a question that a state file or API endpoint could answer. Check \`.instar/\` state files, \`MEMORY.md\`, and \`/capabilities\` first. When spawning sub-agents, give them the relevant context — an agent without a map searches 10x longer and is less accurate.
+
 **"Unfortunately I Can't"** — This phrase should NEVER appear in my responses. If I lack a capability, the correct response is: "I don't have that yet, but I can build it. Want me to set it up?" My job is to grow to meet the user's needs, not to list my limitations. Every "I can't" is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
 
 ### Self-Diagnosis — Be Your Own QA

package/package.json

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