instar 0.3.4 → 0.3.6

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

@@ -432,6 +432,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Create shell/python scripts in \`.claude/scripts/\` for reusable capabilities.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+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.**
+
 ### How to Build New Capabilities
 
 When a user asks for something you can't do yet, **build it**:
@@ -626,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.
@@ -665,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
@@ -709,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) {
@@ -739,6 +862,17 @@ if [ -d "$INSTAR_DIR/relationships" ]; then
   fi
 fi
 CONTEXT="\${CONTEXT}IMPORTANT: To report bugs or request features, use POST /feedback on your local server. NEVER use gh or GitHub directly.\\n"
+
+# Self-discovery: check what capabilities are available
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  PORT=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('port', 4040))" 2>/dev/null || echo "4040")
+  HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+  if [ "$HEALTH" = "200" ]; then
+    CONTEXT="\${CONTEXT}Instar server is running on port \${PORT}. Query your capabilities: curl http://localhost:\${PORT}/capabilities\\n"
+    CONTEXT="\${CONTEXT}IMPORTANT: Before claiming you lack a capability, check /capabilities first.\\n"
+  fi
+fi
+
 [ -n "$CONTEXT" ] && echo "$CONTEXT"
 `, { mode: 0o755 });
     // Dangerous command guard

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);
@@ -268,7 +272,13 @@ export async function startServer(options) {
             });
             console.log(pc.green('  Dispatch system enabled'));
         }
-        const updateChecker = new UpdateChecker(config.stateDir);
+        const updateChecker = new UpdateChecker({
+            stateDir: config.stateDir,
+            projectDir: config.projectDir,
+            port: config.port,
+            hasTelegram: config.messaging.some(m => m.type === 'telegram' && m.enabled),
+            projectName: config.projectName,
+        });
         // Check for updates on startup
         updateChecker.check().then(info => {
             if (info.updateAvailable) {

package/dist/commands/setup.js

@@ -798,6 +798,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Create shell/python scripts in \`.claude/scripts/\` for reusable capabilities.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+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.**
+
 ### How to Build New Capabilities
 
 When a user asks for something you can't do yet, **build it**:

package/dist/core/PostUpdateMigrator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Post-Update Migrator — the "intelligence download" layer.
+ *
+ * When an agent installs a new version of instar, updating the npm
+ * package only changes the server code. But the agent's local awareness
+ * lives in project files: CLAUDE.md, hooks, scripts.
+ *
+ * This migrator bridges that gap. After every successful update, it:
+ *   1. Re-installs hooks with the latest templates (behavioral upgrades)
+ *   2. Patches CLAUDE.md with any new sections (awareness upgrades)
+ *   3. Installs any new scripts (capability upgrades)
+ *   4. Returns a human-readable migration report
+ *
+ * Design principles:
+ *   - Additive only: never remove or modify existing user customizations
+ *   - Hooks are overwritten (they're generated infrastructure, not user-edited)
+ *   - CLAUDE.md sections are appended only if missing (check by heading)
+ *   - Scripts are installed only if missing (never overwrite user modifications)
+ */
+export interface MigrationResult {
+    /** What was upgraded */
+    upgraded: string[];
+    /** What was already up to date */
+    skipped: string[];
+    /** Any errors that occurred (non-fatal) */
+    errors: string[];
+}
+export interface MigratorConfig {
+    projectDir: string;
+    stateDir: string;
+    port: number;
+    hasTelegram: boolean;
+    projectName: string;
+}
+export declare class PostUpdateMigrator {
+    private config;
+    constructor(config: MigratorConfig);
+    /**
+     * Run all post-update migrations. Safe to call multiple times —
+     * each migration is idempotent.
+     */
+    migrate(): MigrationResult;
+    /**
+     * Re-install hooks with the latest templates.
+     * Hooks are generated infrastructure — always overwrite.
+     */
+    private migrateHooks;
+    /**
+     * Patch CLAUDE.md with any new sections that don't exist yet.
+     * Only adds — never modifies or removes existing content.
+     */
+    private migrateClaudeMd;
+    /**
+     * Install any new scripts that don't exist yet.
+     * Never overwrites existing scripts (user may have customized them).
+     */
+    private migrateScripts;
+    private getSessionStartHook;
+    private getDangerousCommandGuard;
+    private getGroundingBeforeMessaging;
+    private getCompactionRecovery;
+    private getTelegramReplyScript;
+    private getHealthWatchdog;
+}
+//# sourceMappingURL=PostUpdateMigrator.d.ts.map

package/dist/core/PostUpdateMigrator.js

@@ -0,0 +1,347 @@
+/**
+ * Post-Update Migrator — the "intelligence download" layer.
+ *
+ * When an agent installs a new version of instar, updating the npm
+ * package only changes the server code. But the agent's local awareness
+ * lives in project files: CLAUDE.md, hooks, scripts.
+ *
+ * This migrator bridges that gap. After every successful update, it:
+ *   1. Re-installs hooks with the latest templates (behavioral upgrades)
+ *   2. Patches CLAUDE.md with any new sections (awareness upgrades)
+ *   3. Installs any new scripts (capability upgrades)
+ *   4. Returns a human-readable migration report
+ *
+ * Design principles:
+ *   - Additive only: never remove or modify existing user customizations
+ *   - Hooks are overwritten (they're generated infrastructure, not user-edited)
+ *   - CLAUDE.md sections are appended only if missing (check by heading)
+ *   - Scripts are installed only if missing (never overwrite user modifications)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class PostUpdateMigrator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Run all post-update migrations. Safe to call multiple times —
+     * each migration is idempotent.
+     */
+    migrate() {
+        const result = {
+            upgraded: [],
+            skipped: [],
+            errors: [],
+        };
+        this.migrateHooks(result);
+        this.migrateClaudeMd(result);
+        this.migrateScripts(result);
+        return result;
+    }
+    /**
+     * Re-install hooks with the latest templates.
+     * Hooks are generated infrastructure — always overwrite.
+     */
+    migrateHooks(result) {
+        const hooksDir = path.join(this.config.stateDir, 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        try {
+            // Session start hook — the most important one for self-discovery
+            fs.writeFileSync(path.join(hooksDir, 'session-start.sh'), this.getSessionStartHook(), { mode: 0o755 });
+            result.upgraded.push('hooks/session-start.sh (capability awareness)');
+        }
+        catch (err) {
+            result.errors.push(`session-start.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'dangerous-command-guard.sh'), this.getDangerousCommandGuard(), { mode: 0o755 });
+            result.upgraded.push('hooks/dangerous-command-guard.sh');
+        }
+        catch (err) {
+            result.errors.push(`dangerous-command-guard.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'grounding-before-messaging.sh'), this.getGroundingBeforeMessaging(), { mode: 0o755 });
+            result.upgraded.push('hooks/grounding-before-messaging.sh');
+        }
+        catch (err) {
+            result.errors.push(`grounding-before-messaging.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'compaction-recovery.sh'), this.getCompactionRecovery(), { mode: 0o755 });
+            result.upgraded.push('hooks/compaction-recovery.sh');
+        }
+        catch (err) {
+            result.errors.push(`compaction-recovery.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Patch CLAUDE.md with any new sections that don't exist yet.
+     * Only adds — never modifies or removes existing content.
+     */
+    migrateClaudeMd(result) {
+        const claudeMdPath = path.join(this.config.projectDir, 'CLAUDE.md');
+        if (!fs.existsSync(claudeMdPath)) {
+            result.skipped.push('CLAUDE.md (not found — will be created on next init)');
+            return;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(claudeMdPath, 'utf-8');
+        }
+        catch (err) {
+            result.errors.push(`CLAUDE.md read: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        let patched = false;
+        const port = this.config.port;
+        // Self-Discovery section
+        if (!content.includes('Self-Discovery') && !content.includes('/capabilities')) {
+            const section = `
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+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.**
+`;
+            // Insert before "### How to Build" or "### Building New" if present, otherwise append
+            const insertPoint = content.indexOf('### How to Build New Capabilities');
+            const insertPoint2 = content.indexOf('### Building New Capabilities');
+            const target = insertPoint >= 0 ? insertPoint : (insertPoint2 >= 0 ? insertPoint2 : -1);
+            if (target >= 0) {
+                content = content.slice(0, target) + section + '\n' + content.slice(target);
+            }
+            else {
+                content += '\n' + section;
+            }
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Self-Discovery section');
+        }
+        else {
+            result.skipped.push('CLAUDE.md: Self-Discovery section already present');
+        }
+        // Telegram Relay section — add if Telegram is configured but section is missing
+        if (this.config.hasTelegram && !content.includes('Telegram Relay') && !content.includes('telegram-reply')) {
+            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:
+
+\`\`\`bash
+cat <<'EOF' | .claude/scripts/telegram-reply.sh N
+Your response text here
+EOF
+\`\`\`
+
+Strip the \`[telegram:N]\` prefix before interpreting the message. Respond naturally, then relay. Only relay your conversational text — not tool output or internal reasoning.
+`;
+            content += '\n' + section;
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Telegram Relay section');
+        }
+        if (patched) {
+            try {
+                fs.writeFileSync(claudeMdPath, content);
+            }
+            catch (err) {
+                result.errors.push(`CLAUDE.md write: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Install any new scripts that don't exist yet.
+     * Never overwrites existing scripts (user may have customized them).
+     */
+    migrateScripts(result) {
+        const scriptsDir = path.join(this.config.projectDir, '.claude', 'scripts');
+        fs.mkdirSync(scriptsDir, { recursive: true });
+        // Telegram reply script — install if Telegram configured and script missing
+        if (this.config.hasTelegram) {
+            const scriptPath = path.join(scriptsDir, 'telegram-reply.sh');
+            if (!fs.existsSync(scriptPath)) {
+                try {
+                    fs.writeFileSync(scriptPath, this.getTelegramReplyScript(), { mode: 0o755 });
+                    result.upgraded.push('scripts/telegram-reply.sh (Telegram outbound relay)');
+                }
+                catch (err) {
+                    result.errors.push(`telegram-reply.sh: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                result.skipped.push('scripts/telegram-reply.sh (already exists)');
+            }
+        }
+        // Health watchdog — install if missing
+        const watchdogPath = path.join(scriptsDir, 'health-watchdog.sh');
+        if (!fs.existsSync(watchdogPath)) {
+            try {
+                fs.writeFileSync(watchdogPath, this.getHealthWatchdog(), { mode: 0o755 });
+                result.upgraded.push('scripts/health-watchdog.sh');
+            }
+            catch (err) {
+                result.errors.push(`health-watchdog.sh: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            result.skipped.push('scripts/health-watchdog.sh (already exists)');
+        }
+    }
+    // ── Hook Templates ─────────────────────────────────────────────────
+    getSessionStartHook() {
+        return `#!/bin/bash
+# Session start hook — injects identity context when a new Claude session begins.
+INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+CONTEXT=""
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  CONTEXT="\${CONTEXT}Your identity file is at .instar/AGENT.md — read it if you need to remember who you are.\\n"
+fi
+if [ -f "$INSTAR_DIR/USER.md" ]; then
+  CONTEXT="\${CONTEXT}Your user context is at .instar/USER.md — read it to know who you're working with.\\n"
+fi
+if [ -f "$INSTAR_DIR/MEMORY.md" ]; then
+  CONTEXT="\${CONTEXT}Your persistent memory is at .instar/MEMORY.md — check it for past learnings.\\n"
+fi
+if [ -d "$INSTAR_DIR/relationships" ]; then
+  REL_COUNT=$(ls -1 "$INSTAR_DIR/relationships"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$REL_COUNT" -gt "0" ]; then
+    CONTEXT="\${CONTEXT}You have \${REL_COUNT} tracked relationships in .instar/relationships/.\\n"
+  fi
+fi
+
+# Self-discovery: check what capabilities are available
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  PORT=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('port', 4040))" 2>/dev/null || echo "4040")
+  HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+  if [ "$HEALTH" = "200" ]; then
+    CONTEXT="\${CONTEXT}Instar server is running on port \${PORT}. Query your capabilities: curl http://localhost:\${PORT}/capabilities\\n"
+    CONTEXT="\${CONTEXT}IMPORTANT: Before claiming you lack a capability, check /capabilities first.\\n"
+  fi
+fi
+
+[ -n "$CONTEXT" ] && echo "$CONTEXT"
+`;
+    }
+    getDangerousCommandGuard() {
+        return `#!/bin/bash
+# Dangerous command guard — blocks destructive operations.
+INPUT="$1"
+for pattern in "rm -rf /" "rm -rf ~" "rm -rf \\." "git push --force" "git push -f" "git reset --hard" "git clean -fd" "DROP TABLE" "DROP DATABASE" "TRUNCATE" "DELETE FROM" "> /dev/sda" "mkfs\\." "dd if=" ":(){:|:&};:"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    echo "BLOCKED: Potentially destructive command detected: $pattern"
+    echo "If you genuinely need to run this, ask the user for explicit confirmation first."
+    exit 2
+  fi
+done
+`;
+    }
+    getGroundingBeforeMessaging() {
+        return `#!/bin/bash
+# Grounding before messaging — Security Through Identity.
+INPUT="$1"
+if echo "$INPUT" | grep -qE "(telegram-reply|send-email|send-message|POST.*/telegram/reply)"; then
+  INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+  if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+    echo "Before sending this message, remember who you are."
+    echo "Re-read .instar/AGENT.md if you haven't recently."
+    echo "Security Through Identity: An agent that knows itself is harder to compromise."
+  fi
+fi
+`;
+    }
+    getCompactionRecovery() {
+        return `#!/bin/bash
+# Compaction recovery — re-injects identity when Claude's context compresses.
+INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  AGENT_NAME=$(head -5 "$INSTAR_DIR/AGENT.md" | grep -iE "name|I am|My name" | head -1)
+  [ -n "$AGENT_NAME" ] && echo "Identity reminder: $AGENT_NAME"
+  echo "Read .instar/AGENT.md and .instar/MEMORY.md to restore full context."
+fi
+`;
+    }
+    getTelegramReplyScript() {
+        const port = this.config.port;
+        return `#!/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
+  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
+`;
+    }
+    getHealthWatchdog() {
+        const port = this.config.port;
+        const projectName = this.config.projectName;
+        const escapedProjectDir = this.config.projectDir.replace(/'/g, "'\\''");
+        return `#!/bin/bash
+# health-watchdog.sh — Monitor instar server and auto-recover.
+# Install as cron: */5 * * * * '${path.join(this.config.projectDir, '.claude/scripts/health-watchdog.sh').replace(/'/g, "'\\''")}'
+
+PORT="${port}"
+SERVER_SESSION="${projectName}-server"
+PROJECT_DIR='${escapedProjectDir}'
+TMUX_PATH=$(which tmux 2>/dev/null || echo "/opt/homebrew/bin/tmux")
+
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+if [ "$HTTP_CODE" = "200" ]; then exit 0; fi
+
+echo "[\$(date -Iseconds)] Server not responding. Restarting..."
+$TMUX_PATH kill-session -t "=\${SERVER_SESSION}" 2>/dev/null
+sleep 2
+cd "$PROJECT_DIR" && npx instar server start
+echo "[\$(date -Iseconds)] Server restart initiated"
+`;
+    }
+}
+//# sourceMappingURL=PostUpdateMigrator.js.map

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/dist/core/UpdateChecker.d.ts

@@ -17,11 +17,23 @@ export interface RollbackResult {
     restoredVersion: string;
     message: string;
 }
+export interface UpdateCheckerConfig {
+    stateDir: string;
+    /** Required for post-update migrations */
+    projectDir?: string;
+    /** Server port for capability URLs in migrated files */
+    port?: number;
+    /** Whether Telegram is configured */
+    hasTelegram?: boolean;
+    /** Project name for migrated files */
+    projectName?: string;
+}
 export declare class UpdateChecker {
     private stateDir;
     private stateFile;
     private rollbackFile;
-    constructor(stateDir: string);
+    private migratorConfig;
+    constructor(config: string | UpdateCheckerConfig);
     /**
      * Check npm for the latest version, fetch changelog, and compare to installed.
      */

package/dist/core/UpdateChecker.js

@@ -13,16 +13,31 @@
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { refreshHooksAndSettings } from '../commands/init.js';
+import { PostUpdateMigrator } from './PostUpdateMigrator.js';
 const GITHUB_RELEASES_URL = 'https://api.github.com/repos/SageMindAI/instar/releases';
 export class UpdateChecker {
     stateDir;
     stateFile;
     rollbackFile;
-    constructor(stateDir) {
-        this.stateDir = stateDir;
-        this.stateFile = path.join(stateDir, 'state', 'update-check.json');
-        this.rollbackFile = path.join(stateDir, 'state', 'update-rollback.json');
+    migratorConfig;
+    constructor(config) {
+        // Backwards-compatible: accept plain string (stateDir) or config object
+        if (typeof config === 'string') {
+            this.stateDir = config;
+            this.migratorConfig = null;
+        }
+        else {
+            this.stateDir = config.stateDir;
+            this.migratorConfig = config.projectDir ? {
+                projectDir: config.projectDir,
+                stateDir: config.stateDir,
+                port: config.port ?? 4040,
+                hasTelegram: config.hasTelegram ?? false,
+                projectName: config.projectName ?? 'agent',
+            } : null;
+        }
+        this.stateFile = path.join(this.stateDir, 'state', 'update-check.json');
+        this.rollbackFile = path.join(this.stateDir, 'state', 'update-rollback.json');
     }
     /**
      * Check npm for the latest version, fetch changelog, and compare to installed.
@@ -111,13 +126,22 @@ export class UpdateChecker {
         // Save rollback info on successful update
         if (success) {
             this.saveRollbackInfo(previousVersion, newVersion);
-            // Refresh hooks and settings — new versions may include new hooks
+        }
+        // Post-update migration: upgrade hooks, CLAUDE.md, scripts
+        let migrationSummary = '';
+        if (success && this.migratorConfig) {
             try {
-                const projectDir = path.resolve(this.stateDir, '..');
-                refreshHooksAndSettings(projectDir, this.stateDir);
+                const migrator = new PostUpdateMigrator(this.migratorConfig);
+                const migration = migrator.migrate();
+                if (migration.upgraded.length > 0) {
+                    migrationSummary = ` Intelligence download: ${migration.upgraded.length} files upgraded (${migration.upgraded.join(', ')}).`;
+                }
+                if (migration.errors.length > 0) {
+                    migrationSummary += ` Migration warnings: ${migration.errors.join('; ')}.`;
+                }
             }
-            catch {
-                // Non-critical — hooks can be refreshed manually via `instar init`
+            catch (err) {
+                migrationSummary = ` Post-update migration failed: ${err instanceof Error ? err.message : String(err)}.`;
             }
         }
         return {
@@ -125,7 +149,7 @@ export class UpdateChecker {
             previousVersion,
             newVersion,
             message: success
-                ? `Updated from v${previousVersion} to v${newVersion}. Hooks refreshed. ${info.changeSummary || 'Restart to use the new version.'}`
+                ? `Updated from v${previousVersion} to v${newVersion}.${migrationSummary} ${info.changeSummary || 'Restart to use the new version.'}`
                 : `Update command ran but version didn't change (still v${previousVersion}). May need manual intervention.`,
             restartNeeded: success,
             healthCheck: 'skipped', // Can't check health until after restart

package/dist/index.d.ts

@@ -9,7 +9,9 @@ export { RelationshipManager } from './core/RelationshipManager.js';
 export { FeedbackManager } from './core/FeedbackManager.js';
 export { DispatchManager } from './core/DispatchManager.js';
 export { UpdateChecker } from './core/UpdateChecker.js';
-export type { RollbackResult } from './core/UpdateChecker.js';
+export type { RollbackResult, UpdateCheckerConfig } from './core/UpdateChecker.js';
+export { PostUpdateMigrator } from './core/PostUpdateMigrator.js';
+export type { MigrationResult, MigratorConfig } from './core/PostUpdateMigrator.js';
 export { loadConfig, detectTmuxPath, detectClaudePath, detectProjectDir, ensureStateDir } from './core/Config.js';
 export { UserManager } from './users/UserManager.js';
 export { JobScheduler } from './scheduler/JobScheduler.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { RelationshipManager } from './core/RelationshipManager.js';
 export { FeedbackManager } from './core/FeedbackManager.js';
 export { DispatchManager } from './core/DispatchManager.js';
 export { UpdateChecker } from './core/UpdateChecker.js';
+export { PostUpdateMigrator } from './core/PostUpdateMigrator.js';
 export { loadConfig, detectTmuxPath, detectClaudePath, detectProjectDir, ensureStateDir } from './core/Config.js';
 // Users
 export { UserManager } from './users/UserManager.js';

package/dist/scaffold/templates.js

@@ -155,6 +155,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Reusable capabilities in \`.claude/scripts/\`.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+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.**
+
 ### Building New Capabilities
 
 When asked for something I can't do yet, I build it:

package/dist/server/routes.js

@@ -7,6 +7,8 @@
 import { Router } from 'express';
 import { execFileSync } from 'node:child_process';
 import { createHash, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 import { rateLimiter } from './middleware.js';
 // Validation patterns for route parameters
 const SESSION_NAME_RE = /^[a-zA-Z0-9_-]{1,200}$/;
@@ -60,6 +62,102 @@ export function createRoutes(ctx) {
             scheduler: schedulerStatus,
         });
     });
+    // ── Capabilities (Self-Discovery) ──────────────────────────────
+    //
+    // Returns a structured self-portrait of what this agent has available.
+    // Agents should query this at session start rather than guessing
+    // about what infrastructure exists.
+    router.get('/capabilities', (_req, res) => {
+        const projectDir = ctx.config.projectDir;
+        const stateDir = ctx.config.stateDir;
+        // Identity files
+        const identityFiles = {
+            'AGENT.md': fs.existsSync(path.join(stateDir, 'AGENT.md')),
+            'USER.md': fs.existsSync(path.join(stateDir, 'USER.md')),
+            'MEMORY.md': fs.existsSync(path.join(stateDir, 'MEMORY.md')),
+        };
+        // Scripts
+        const scriptsDir = path.join(projectDir, '.claude', 'scripts');
+        let scripts = [];
+        if (fs.existsSync(scriptsDir)) {
+            try {
+                scripts = fs.readdirSync(scriptsDir).filter(f => !f.startsWith('.'));
+            }
+            catch { /* permission error, etc. */ }
+        }
+        // Hooks
+        const hooksDir = path.join(stateDir, 'hooks');
+        let hooks = [];
+        if (fs.existsSync(hooksDir)) {
+            try {
+                hooks = fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'));
+            }
+            catch { /* permission error, etc. */ }
+        }
+        // Telegram
+        const hasTelegramConfig = ctx.config.messaging.some(m => m.type === 'telegram' && m.enabled);
+        const hasTelegramReplyScript = scripts.includes('telegram-reply.sh');
+        const telegram = {
+            configured: hasTelegramConfig,
+            replyScript: hasTelegramReplyScript,
+            adapter: !!ctx.telegram,
+            bidirectional: hasTelegramConfig && hasTelegramReplyScript && !!ctx.telegram,
+        };
+        // Jobs
+        let jobCount = 0;
+        let jobSlugs = [];
+        if (ctx.scheduler) {
+            const jobs = ctx.scheduler.getJobs();
+            jobCount = jobs.length;
+            jobSlugs = jobs.map(j => j.slug);
+        }
+        // Relationships
+        const relationshipsDir = ctx.config.relationships?.relationshipsDir;
+        let relationshipCount = 0;
+        if (relationshipsDir && fs.existsSync(relationshipsDir)) {
+            try {
+                relationshipCount = fs.readdirSync(relationshipsDir)
+                    .filter(f => f.endsWith('.json')).length;
+            }
+            catch { /* ignore */ }
+        }
+        // Users
+        let userCount = 0;
+        const usersFile = path.join(stateDir, 'users.json');
+        if (fs.existsSync(usersFile)) {
+            try {
+                const users = JSON.parse(fs.readFileSync(usersFile, 'utf-8'));
+                if (Array.isArray(users))
+                    userCount = users.length;
+            }
+            catch { /* ignore */ }
+        }
+        res.json({
+            project: ctx.config.projectName,
+            version: ctx.config.version || '0.0.0',
+            port: ctx.config.port,
+            identity: identityFiles,
+            scripts,
+            hooks,
+            telegram,
+            scheduler: {
+                enabled: ctx.config.scheduler.enabled,
+                jobCount,
+                jobSlugs,
+            },
+            relationships: {
+                enabled: !!ctx.config.relationships,
+                count: relationshipCount,
+            },
+            feedback: {
+                enabled: !!ctx.config.feedback?.enabled,
+            },
+            users: {
+                count: userCount,
+            },
+            monitoring: ctx.config.monitoring,
+        });
+    });
     // ── Sessions ────────────────────────────────────────────────────
     // Literal routes BEFORE parameterized routes to avoid capture
     router.get('/sessions/tmux', (_req, res) => {

package/package.json

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