instar 0.4.7 → 0.4.9

package/README.md

@@ -20,17 +20,19 @@
 
 ---
 
+> **This is power-user infrastructure.** Instar gives Claude Code full autonomous access to your machine -- no permission prompts, no sandbox. It's built for developers who want a genuine AI partner, not a guarded assistant. If that sounds like too much trust, it probably isn't for you. If it sounds like exactly what you've been waiting for, read on.
+
 Instar gives Claude Code agents a **persistent body** -- a server that runs 24/7, a scheduler that executes jobs on cron, messaging integrations, relationship tracking, and the self-awareness to grow their own capabilities.
 
 Named after the developmental stages between molts in arthropods, where each instar is more developed than the last.
 
 ## The Problem
 
-**Without Instar**, Claude Code is a CLI tool. You open a terminal, type a prompt, get a response, close the terminal. No persistence. No scheduling. No way to reach you.
+**Without Instar**, Claude Code is a CLI tool. You open a terminal, type a prompt, get a response, close the terminal. No persistence. No scheduling. No way to reach you. Every session starts from zero.
 
-**With Instar**, Claude Code becomes an agent. It runs in the background, checks your email on a schedule, monitors your services, messages you on Telegram when something needs attention, and builds new capabilities when you ask for something it can't do yet.
+**With Instar**, Claude Code becomes your partner. It runs in the background, checks your email on a schedule, monitors your services, messages you on Telegram when something needs attention, remembers who it's talked to, and builds new capabilities when you ask for something it can't do yet. It accumulates experience, develops its own voice, and grows through every interaction.
 
-The difference isn't features. It's a shift in what Claude Code *is* -- from a tool you use to an agent that works alongside you.
+The difference isn't features. It's a shift in what Claude Code *is* -- from a tool you use to an agent that works alongside you. This is the cutting edge of what's possible with AI agents today -- not a demo, not a toy, but genuine autonomous partnership between a human and an AI.
 
 ## Two Ways to Use Instar
 
@@ -413,11 +415,13 @@ Instead of per-action permission prompts, Instar pushes security to a higher lev
 - The agent **is directed** by its CLAUDE.md, identity files, and behavioral hooks to stay within its project scope -- but this is behavioral guidance, not a technical boundary
 - All behavioral hooks, identity files, and CLAUDE.md instructions are **in your project** and fully editable by you
 
-### Proceed at Your Own Risk
+### Who This Is For
+
+Instar is built for developers and power users who want to work **with** an AI, not just **use** one. You're giving your agent the same access to your machine that any program running under your user account has. The security model relies on intelligent behavior -- identity, hooks, coherence, and grounding -- rather than permission dialogs or sandboxing.
 
-This is infrastructure for people who want genuine AI autonomy, not a sandbox demo. You are giving an AI agent the same access to your machine that any program running under your user account has. The security model relies on intelligent behavior (identity, hooks, coherence) rather than permission dialogs or sandboxing.
+This is the trade-off at the heart of genuine AI autonomy: you can have an agent that asks permission for everything and does nothing on its own, or you can have a partner that operates with real agency, guided by coherent identity and structural guardrails. Instar is the latter.
 
-If you're not comfortable with that trade-off, Claude Code's default permission mode may be a better fit for your use case.
+**Proceed at your own risk.** If you're not comfortable giving an AI agent this level of access, Claude Code's default permission mode is a perfectly good way to work. But if you want to see what an AI agent can actually do when you stop holding it back -- this is the infrastructure for that.
 
 ## How the Agent Grows
 

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.7",
+  "version": "0.4.9",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",