instar 0.7.14 → 0.7.16

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

@@ -651,13 +651,29 @@ The greeting should be **in the agent's voice** AND explain how Telegram topics
 
 Adapt the tone and examples to the agent's personality and role. Keep it warm and practical.
 
-### Step 5c: Tell the User
+### Step 5c: Install Auto-Start
 
-After the server is running and the greeting is sent:
+After the server starts, install auto-start so the agent comes back on login:
+
+```bash
+npx instar autostart install --dir <project_dir>
+```
+
+This creates a macOS LaunchAgent or Linux systemd service. The agent will start automatically whenever the user logs in — nothing to remember.
+
+### Step 5d: Tell the User
+
+After the server is running, auto-start is installed, and the greeting is sent:
 
 > "All done! [Agent name] just messaged you in the Lifeline topic on Telegram. From here on, that's your primary channel — just talk to your agent there."
 >
-> "As long as your computer is running the Instar server, your agent is available."
+> "I've set up auto-start — your agent will come back automatically when you log in. As long as your computer is on and awake, Telegram just works."
+
+If auto-start install failed, explain the fallback:
+
+> "Your agent runs on this computer. If your computer restarts, you'll need to run `instar server start` to bring it back."
+
+Keep it matter-of-fact, not alarming.
 
 **Do NOT present a list of CLI commands or next steps.** The setup wizard's job is done. The user's next action is opening Telegram and replying to their agent.
 

package/.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

package/.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_evM5LcItYL3IAmw8zNvEPGrHeaya","orgId":"team_dHctwIDcV3X9ydapQlCPHFGI","projectName":"claude-agent-kit"}

package/dist/cli.js

@@ -547,5 +547,82 @@ program
         console.log();
     }
 });
+// ── Auto-Start ───────────────────────────────────────────────────
+const autostartCmd = program
+    .command('autostart')
+    .description('Manage auto-start on login (agent starts when you log into your computer)');
+autostartCmd
+    .command('install')
+    .description('Install auto-start so your agent starts on login')
+    .option('-d, --dir <path>', 'Project directory')
+    .action(async (opts) => {
+    const { loadConfig } = await import('./core/Config.js');
+    const { installAutoStart } = await import('./commands/setup.js');
+    const config = loadConfig(opts.dir);
+    const hasTelegram = config.messaging?.some((m) => m.type === 'telegram') ?? false;
+    const installed = installAutoStart(config.projectName, config.projectDir, hasTelegram);
+    if (installed) {
+        console.log(pc.green(`Auto-start installed for "${config.projectName}".`));
+        console.log(pc.dim('Your agent will start automatically when you log in.'));
+    }
+    else {
+        console.log(pc.red('Failed to install auto-start.'));
+        console.log(pc.dim(`Platform: ${process.platform} — auto-start supports macOS and Linux.`));
+    }
+});
+autostartCmd
+    .command('uninstall')
+    .description('Remove auto-start')
+    .option('-d, --dir <path>', 'Project directory')
+    .action(async (opts) => {
+    const { loadConfig } = await import('./core/Config.js');
+    const { uninstallAutoStart } = await import('./commands/setup.js');
+    const config = loadConfig(opts.dir);
+    const removed = uninstallAutoStart(config.projectName);
+    if (removed) {
+        console.log(pc.green(`Auto-start removed for "${config.projectName}".`));
+    }
+    else {
+        console.log(pc.yellow('No auto-start found to remove.'));
+    }
+});
+autostartCmd
+    .command('status')
+    .description('Check if auto-start is installed')
+    .option('-d, --dir <path>', 'Project directory')
+    .action(async (opts) => {
+    const { loadConfig } = await import('./core/Config.js');
+    const config = loadConfig(opts.dir);
+    const os = await import('node:os');
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    if (process.platform === 'darwin') {
+        const label = `ai.instar.${config.projectName}`;
+        const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+        if (fs.existsSync(plistPath)) {
+            console.log(pc.green(`Auto-start is installed (macOS LaunchAgent: ${label})`));
+            console.log(pc.dim(`  Plist: ${plistPath}`));
+        }
+        else {
+            console.log(pc.yellow('Auto-start is not installed.'));
+            console.log(pc.dim('  Install with: instar autostart install'));
+        }
+    }
+    else if (process.platform === 'linux') {
+        const serviceName = `instar-${config.projectName}.service`;
+        const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', serviceName);
+        if (fs.existsSync(servicePath)) {
+            console.log(pc.green(`Auto-start is installed (systemd user service: ${serviceName})`));
+            console.log(pc.dim(`  Service: ${servicePath}`));
+        }
+        else {
+            console.log(pc.yellow('Auto-start is not installed.'));
+            console.log(pc.dim('  Install with: instar autostart install'));
+        }
+    }
+    else {
+        console.log(pc.yellow(`Auto-start is not supported on ${process.platform}.`));
+    }
+});
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/commands/setup.d.ts

@@ -21,4 +21,16 @@
 export declare function runSetup(opts?: {
     classic?: boolean;
 }): Promise<void>;
+/**
+ * Install auto-start so the agent's lifeline process starts on login.
+ * macOS: LaunchAgent plist in ~/Library/LaunchAgents/
+ * Linux: systemd user service in ~/.config/systemd/user/
+ *
+ * Returns true if auto-start was installed successfully.
+ */
+export declare function installAutoStart(projectName: string, projectDir: string, hasTelegram: boolean): boolean;
+/**
+ * Remove auto-start for a project.
+ */
+export declare function uninstallAutoStart(projectName: string): boolean;
 //# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.js

@@ -17,6 +17,7 @@
 import { execFileSync, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import pc from 'picocolors';
 import { input, confirm, select, number } from '@inquirer/prompts';
@@ -449,6 +450,12 @@ async function runClassicSetup() {
     console.log(pc.dim('  Starting server...'));
     const { startServer } = await import('./server.js');
     await startServer({ foreground: false });
+    // ── Auto-start on login ──────────────────────────────────────────
+    const hasTelegram = !!telegramConfig?.chatId;
+    const autoStartInstalled = installAutoStart(projectName, projectDir, hasTelegram);
+    if (autoStartInstalled) {
+        console.log(pc.green('  ✓ Auto-start installed — your agent will start on login.'));
+    }
     if (telegramConfig?.chatId) {
         // Create the Lifeline topic — the always-available channel
         let lifelineThreadId = null;
@@ -462,6 +469,19 @@ async function runClassicSetup() {
             const parsed = JSON.parse(topicResult);
             if (parsed.ok && parsed.result?.message_thread_id) {
                 lifelineThreadId = parsed.result.message_thread_id;
+                // Persist lifelineTopicId back to config.json
+                try {
+                    const configPath = path.join(stateDir, 'config.json');
+                    const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                    const tgEntry = rawConfig.messaging?.find((m) => m.type === 'telegram');
+                    if (tgEntry?.config) {
+                        tgEntry.config.lifelineTopicId = lifelineThreadId;
+                        const tmpPath = `${configPath}.${process.pid}.tmp`;
+                        fs.writeFileSync(tmpPath, JSON.stringify(rawConfig, null, 2));
+                        fs.renameSync(tmpPath, configPath);
+                    }
+                }
+                catch { /* non-fatal */ }
             }
         }
         catch {
@@ -480,6 +500,8 @@ async function runClassicSetup() {
                 '- I can proactively create topics when something needs attention',
                 '- Lifeline is always here for anything that doesn\'t fit elsewhere',
                 '',
+                '_I run on your computer, so I\'m available as long as it\'s on and awake. If it sleeps, I\'ll pick up messages when it wakes back up._',
+                '',
                 'What should we work on first?',
             ].join('\n');
             const payload = {
@@ -504,7 +526,16 @@ async function runClassicSetup() {
         const topicNote = lifelineThreadId ? ' in the Lifeline topic' : '';
         console.log(pc.bold(`  All done! ${projectName} just messaged you${topicNote} on Telegram.`));
         console.log(pc.dim('  That\'s your primary channel from here on — no terminal needed.'));
-        console.log(pc.dim('  As long as your computer is running the Instar server, your agent is available.'));
+        console.log();
+        if (autoStartInstalled) {
+            console.log(pc.dim('  Your agent starts automatically when you log in — nothing to remember.'));
+            console.log(pc.dim('  As long as your computer is on and awake, Telegram just works.'));
+        }
+        else {
+            console.log(pc.dim('  Your agent runs on this computer. As long as it\'s on and awake,'));
+            console.log(pc.dim('  your agent is reachable via Telegram. You\'ll need to run'));
+            console.log(pc.dim(`  ${pc.cyan('instar server start')} after a reboot.`));
+        }
     }
     else {
         console.log();
@@ -570,6 +601,208 @@ function isInstarGlobal() {
         return false;
     }
 }
+// ── Auto-Start on Login ─────────────────────────────────────────
+/**
+ * Install auto-start so the agent's lifeline process starts on login.
+ * macOS: LaunchAgent plist in ~/Library/LaunchAgents/
+ * Linux: systemd user service in ~/.config/systemd/user/
+ *
+ * Returns true if auto-start was installed successfully.
+ */
+export function installAutoStart(projectName, projectDir, hasTelegram) {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        return installMacOSLaunchAgent(projectName, projectDir, hasTelegram);
+    }
+    else if (platform === 'linux') {
+        return installLinuxSystemdService(projectName, projectDir, hasTelegram);
+    }
+    else {
+        // Windows or other — no auto-start support yet
+        return false;
+    }
+}
+/**
+ * Remove auto-start for a project.
+ */
+export function uninstallAutoStart(projectName) {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        const label = `ai.instar.${projectName}`;
+        const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+        // Unload if loaded
+        try {
+            execFileSync('launchctl', ['bootout', `gui/${process.getuid?.() ?? 501}`, plistPath], { stdio: 'ignore' });
+        }
+        catch { /* not loaded */ }
+        // Remove file
+        try {
+            fs.unlinkSync(plistPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    else if (platform === 'linux') {
+        const serviceName = `instar-${projectName}.service`;
+        const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', serviceName);
+        try {
+            execFileSync('systemctl', ['--user', 'disable', serviceName], { stdio: 'ignore' });
+            execFileSync('systemctl', ['--user', 'stop', serviceName], { stdio: 'ignore' });
+        }
+        catch { /* not loaded */ }
+        try {
+            fs.unlinkSync(servicePath);
+            execFileSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function findNodePath() {
+    try {
+        return execFileSync('which', ['node'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return '/usr/local/bin/node';
+    }
+}
+function findInstarCli() {
+    // Find the actual instar CLI entry point
+    try {
+        const globalPath = execFileSync('which', ['instar'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (globalPath && !globalPath.includes('.npm/_npx')) {
+            return globalPath;
+        }
+    }
+    catch { /* not global */ }
+    // Fallback: use the dist/cli.js from the npm package
+    const cliPath = new URL('../cli.js', import.meta.url).pathname;
+    if (fs.existsSync(cliPath)) {
+        return cliPath;
+    }
+    return 'instar';
+}
+function installMacOSLaunchAgent(projectName, projectDir, hasTelegram) {
+    const label = `ai.instar.${projectName}`;
+    const launchAgentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const plistPath = path.join(launchAgentsDir, `${label}.plist`);
+    const logDir = path.join(projectDir, '.instar', 'logs');
+    const nodePath = findNodePath();
+    const instarCli = findInstarCli();
+    // Determine what to start: lifeline if Telegram configured, otherwise just the server
+    const command = hasTelegram ? 'lifeline' : 'server';
+    const args = hasTelegram
+        ? [instarCli, 'lifeline', 'start', '--dir', projectDir]
+        : [instarCli, 'server', 'start', '--foreground', '--dir', projectDir];
+    // If instar CLI is a node script (not a binary), prepend node
+    const isNodeScript = instarCli.endsWith('.js') || instarCli.endsWith('.mjs');
+    const programArgs = isNodeScript ? [nodePath, ...args] : args;
+    // Build the plist XML
+    const argsXml = programArgs.map(a => `      <string>${escapeXml(a)}</string>`).join('\n');
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${escapeXml(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argsXml}
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${escapeXml(projectDir)}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${escapeXml(path.join(logDir, `${command}-launchd.log`))}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(path.join(logDir, `${command}-launchd.err`))}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${escapeXml(process.env.PATH || '/usr/local/bin:/usr/bin:/bin')}</string>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>`;
+    try {
+        fs.mkdirSync(launchAgentsDir, { recursive: true });
+        fs.mkdirSync(logDir, { recursive: true });
+        fs.writeFileSync(plistPath, plist);
+        // Load the agent
+        try {
+            // Unload first if already loaded
+            execFileSync('launchctl', ['bootout', `gui/${process.getuid?.() ?? 501}`, plistPath], { stdio: 'ignore' });
+        }
+        catch { /* not loaded yet — fine */ }
+        execFileSync('launchctl', ['bootstrap', `gui/${process.getuid?.() ?? 501}`, plistPath], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function installLinuxSystemdService(projectName, projectDir, hasTelegram) {
+    const serviceName = `instar-${projectName}.service`;
+    const serviceDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    const servicePath = path.join(serviceDir, serviceName);
+    const nodePath = findNodePath();
+    const instarCli = findInstarCli();
+    const command = hasTelegram ? 'lifeline' : 'server';
+    const args = hasTelegram
+        ? `${instarCli} lifeline start --dir ${projectDir}`
+        : `${instarCli} server start --foreground --dir ${projectDir}`;
+    const isNodeScript = instarCli.endsWith('.js') || instarCli.endsWith('.mjs');
+    const execStart = isNodeScript ? `${nodePath} ${args}` : args;
+    const service = `[Unit]
+Description=Instar Agent - ${projectName}
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+WorkingDirectory=${projectDir}
+Restart=always
+RestartSec=10
+Environment=PATH=${process.env.PATH || '/usr/local/bin:/usr/bin:/bin'}
+
+[Install]
+WantedBy=default.target
+`;
+    try {
+        fs.mkdirSync(serviceDir, { recursive: true });
+        fs.writeFileSync(servicePath, service);
+        execFileSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+        execFileSync('systemctl', ['--user', 'enable', serviceName], { stdio: 'ignore' });
+        execFileSync('systemctl', ['--user', 'start', serviceName], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
 // ── Prompt Helpers ───────────────────────────────────────────────
 /**
  * Full Telegram walkthrough. Returns config or null if skipped.

package/dist/lifeline/TelegramLifeline.d.ts

@@ -29,6 +29,7 @@ export declare class TelegramLifeline {
     private offsetPath;
     private stopHeartbeat;
     private replayInterval;
+    private lifelineTopicId;
     constructor(projectDir?: string);
     /**
      * Start the lifeline — begins Telegram polling and server supervision.
@@ -43,6 +44,14 @@ export declare class TelegramLifeline {
     private handleLifelineCommand;
     private replayQueue;
     private notifyServerDown;
+    /**
+     * Ensure the Lifeline topic exists. Recreates if deleted.
+     */
+    private ensureLifelineTopic;
+    /**
+     * Persist the Lifeline topic ID to config.json.
+     */
+    private persistLifelineTopicId;
     private sendToTopic;
     private getUpdates;
     private apiCall;

package/dist/lifeline/TelegramLifeline.js

@@ -36,6 +36,7 @@ export class TelegramLifeline {
     offsetPath;
     stopHeartbeat = null;
     replayInterval = null;
+    lifelineTopicId = null;
     constructor(projectDir) {
         this.projectConfig = loadConfig(projectDir);
         ensureStateDir(this.projectConfig.stateDir);
@@ -81,6 +82,11 @@ export class TelegramLifeline {
         }
         catch { /* non-critical */ }
         this.stopHeartbeat = startHeartbeat(`${this.projectConfig.projectName}-lifeline`);
+        // Ensure Lifeline topic exists (auto-recreate if deleted)
+        this.lifelineTopicId = await this.ensureLifelineTopic();
+        if (this.lifelineTopicId) {
+            console.log(pc.green(`  Lifeline topic: ${this.lifelineTopicId}`));
+        }
         // Start server supervisor
         const serverStarted = await this.supervisor.start();
         if (serverStarted) {
@@ -300,8 +306,82 @@ export class TelegramLifeline {
     }
     // ── Notifications ─────────────────────────────────────────
     async notifyServerDown(reason) {
-        // Send to General topic (1) — since we don't know which topic the user is watching
-        await this.sendToTopic(1, `Server went down: ${reason}\n\nYour messages will be queued until recovery. Use /lifeline status to check.`).catch(() => { });
+        // Send to Lifeline topic if available, otherwise General
+        const topicId = this.lifelineTopicId ?? 1;
+        await this.sendToTopic(topicId, `Server went down: ${reason}\n\nYour messages will be queued until recovery. Use /lifeline status to check.`).catch(() => { });
+    }
+    // ── Lifeline Topic ──────────────────────────────────────────
+    /**
+     * Ensure the Lifeline topic exists. Recreates if deleted.
+     */
+    async ensureLifelineTopic() {
+        const existingId = this.config.lifelineTopicId;
+        if (existingId) {
+            // Verify it still exists
+            try {
+                await this.apiCall('sendMessage', {
+                    chat_id: this.config.chatId,
+                    message_thread_id: existingId,
+                    text: '🟢 Lifeline connected.',
+                });
+                return existingId;
+            }
+            catch (err) {
+                const errStr = String(err);
+                if (errStr.includes('thread not found') || errStr.includes('TOPIC_DELETED') ||
+                    errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
+                    console.log(`[Lifeline] Topic ${existingId} was deleted — recreating`);
+                }
+                else {
+                    // Non-fatal error (network etc.) — assume it still exists
+                    console.warn(`[Lifeline] Topic check failed (non-fatal): ${err}`);
+                    return existingId;
+                }
+            }
+        }
+        // Create or recreate
+        try {
+            const result = await this.apiCall('createForumTopic', {
+                chat_id: this.config.chatId,
+                name: 'Lifeline',
+                icon_color: 9367192, // green
+            });
+            const topicId = result.message_thread_id;
+            this.config.lifelineTopicId = topicId;
+            this.persistLifelineTopicId(topicId);
+            console.log(`[Lifeline] ${existingId ? 'Recreated' : 'Created'} Lifeline topic: ${topicId}`);
+            // Send welcome message in new topic
+            await this.sendToTopic(topicId, '🟢 Lifeline connected. This topic is always available — even when the server is down.');
+            return topicId;
+        }
+        catch (err) {
+            console.error(`[Lifeline] Failed to create Lifeline topic: ${err}`);
+            return null;
+        }
+    }
+    /**
+     * Persist the Lifeline topic ID to config.json.
+     */
+    persistLifelineTopicId(topicId) {
+        try {
+            const configPath = path.join(this.projectConfig.projectDir, '.instar', 'config.json');
+            if (fs.existsSync(configPath)) {
+                const raw = fs.readFileSync(configPath, 'utf-8');
+                const config = JSON.parse(raw);
+                if (Array.isArray(config.messaging)) {
+                    const entry = config.messaging.find((m) => m.type === 'telegram');
+                    if (entry?.config) {
+                        entry.config.lifelineTopicId = topicId;
+                        const tmpPath = `${configPath}.${process.pid}.tmp`;
+                        fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2));
+                        fs.renameSync(tmpPath, configPath);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`[Lifeline] Failed to persist lifelineTopicId: ${err}`);
+        }
     }
     // ── Telegram API ──────────────────────────────────────────
     async sendToTopic(topicId, text) {

package/dist/messaging/TelegramAdapter.d.ts

@@ -22,6 +22,8 @@ export interface TelegramConfig {
     voiceProvider?: string;
     /** Stall detection timeout in minutes (default: 5, 0 to disable) */
     stallTimeoutMinutes?: number;
+    /** Lifeline topic thread ID — the always-available channel. Auto-recreated if deleted. */
+    lifelineTopicId?: number;
 }
 export interface SendResult {
     /** Telegram message ID */
@@ -100,6 +102,19 @@ export declare class TelegramAdapter implements MessagingAdapter {
         topicId: number;
         name: string;
     }>;
+    /**
+     * Get the Lifeline topic ID (if configured).
+     */
+    getLifelineTopicId(): number | undefined;
+    /**
+     * Ensure the Lifeline topic exists. If it was deleted, recreate it.
+     * Called on startup and can be called periodically.
+     */
+    ensureLifelineTopic(): Promise<number | null>;
+    /**
+     * Persist the Lifeline topic ID back to config.json so it survives restarts.
+     */
+    private persistLifelineTopicId;
     /**
      * Close a forum topic.
      */

package/dist/messaging/TelegramAdapter.js

@@ -87,6 +87,8 @@ export class TelegramAdapter {
         this.polling = true;
         this.startedAt = new Date();
         this.consecutivePollErrors = 0;
+        // Ensure Lifeline topic exists (auto-recreate if deleted)
+        await this.ensureLifelineTopic();
         console.log(`[telegram] Starting long-polling...`);
         this.poll();
         // Start stall detection if configured
@@ -180,6 +182,97 @@ export class TelegramAdapter {
         console.log(`[telegram] Created forum topic: "${name}" (ID: ${result.message_thread_id})`);
         return { topicId: result.message_thread_id, name: result.name };
     }
+    /**
+     * Get the Lifeline topic ID (if configured).
+     */
+    getLifelineTopicId() {
+        return this.config.lifelineTopicId;
+    }
+    /**
+     * Ensure the Lifeline topic exists. If it was deleted, recreate it.
+     * Called on startup and can be called periodically.
+     */
+    async ensureLifelineTopic() {
+        if (!this.config.lifelineTopicId) {
+            // No lifeline topic configured — create one
+            try {
+                const topic = await this.createForumTopic('Lifeline', 9367192); // Green
+                this.config.lifelineTopicId = topic.topicId;
+                this.persistLifelineTopicId(topic.topicId);
+                console.log(`[telegram] Created Lifeline topic: ${topic.topicId}`);
+                return topic.topicId;
+            }
+            catch (err) {
+                console.error(`[telegram] Failed to create Lifeline topic: ${err}`);
+                return null;
+            }
+        }
+        // Lifeline topic ID exists — verify it's still valid by sending a test
+        try {
+            await this.apiCall('sendMessage', {
+                chat_id: this.config.chatId,
+                message_thread_id: this.config.lifelineTopicId,
+                text: '🟢 Lifeline connected.',
+            });
+            console.log(`[telegram] Lifeline topic verified: ${this.config.lifelineTopicId}`);
+            return this.config.lifelineTopicId;
+        }
+        catch (err) {
+            const errStr = String(err);
+            // Topic was deleted — "message thread not found" or "TOPIC_CLOSED" or similar
+            if (errStr.includes('thread not found') || errStr.includes('TOPIC_DELETED') ||
+                errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
+                console.log(`[telegram] Lifeline topic ${this.config.lifelineTopicId} was deleted — recreating`);
+                try {
+                    const topic = await this.createForumTopic('Lifeline', 9367192);
+                    this.config.lifelineTopicId = topic.topicId;
+                    this.persistLifelineTopicId(topic.topicId);
+                    console.log(`[telegram] Recreated Lifeline topic: ${topic.topicId}`);
+                    return topic.topicId;
+                }
+                catch (recreateErr) {
+                    console.error(`[telegram] Failed to recreate Lifeline topic: ${recreateErr}`);
+                    return null;
+                }
+            }
+            // Some other error (network, etc.) — don't recreate, just warn
+            console.warn(`[telegram] Lifeline topic check failed (non-fatal): ${err}`);
+            return this.config.lifelineTopicId;
+        }
+    }
+    /**
+     * Persist the Lifeline topic ID back to config.json so it survives restarts.
+     */
+    persistLifelineTopicId(topicId) {
+        try {
+            // Find config.json in state dir's parent (stateDir is .instar/state or .instar)
+            const candidates = [
+                path.join(this.stateDir, '..', 'config.json'),
+                path.join(this.stateDir, 'config.json'),
+            ];
+            for (const configPath of candidates) {
+                if (fs.existsSync(configPath)) {
+                    const raw = fs.readFileSync(configPath, 'utf-8');
+                    const config = JSON.parse(raw);
+                    // Find the telegram messaging config and update it
+                    if (Array.isArray(config.messaging)) {
+                        const telegramEntry = config.messaging.find((m) => m.type === 'telegram');
+                        if (telegramEntry?.config) {
+                            telegramEntry.config.lifelineTopicId = topicId;
+                            const tmpPath = `${configPath}.${process.pid}.tmp`;
+                            fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2));
+                            fs.renameSync(tmpPath, configPath);
+                            console.log(`[telegram] Saved lifelineTopicId=${topicId} to config`);
+                            return;
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`[telegram] Failed to persist lifelineTopicId: ${err}`);
+        }
+    }
     /**
      * Close a forum topic.
      */

package/package.json

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