instar 0.7.43 → 0.7.45

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

@@ -646,50 +646,19 @@ If Telegram was set up in Phase 3, install the relay script that lets Claude ses
 mkdir -p .claude/scripts
 ```
 
-Write `.claude/scripts/telegram-reply.sh`:
+**IMPORTANT: Do NOT write a custom telegram-reply.sh.** Instead, copy the canonical version from the instar package:
 
 ```bash
-#!/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
-
-PORT=<PORT>
-
-# Get message from args or stdin
-if [ $# -gt 0 ]; then
-  MESSAGE="$*"
-else
-  MESSAGE=$(cat)
-fi
-
-if [ -z "$MESSAGE" ]; then
-  echo "No message provided" >&2
-  exit 1
-fi
-
-# Send via instar server API
-curl -s -X POST "http://localhost:${PORT}/telegram/topic/${TOPIC_ID}/send" \
-  -H 'Content-Type: application/json' \
-  -d "$(jq -n --arg text "$MESSAGE" '{text: $text}')" > /dev/null 2>&1
-
-echo "Sent $(echo "$MESSAGE" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+cp "$(dirname "$(which instar 2>/dev/null || echo "$(npm root -g)/instar")")/templates/scripts/telegram-reply.sh" .claude/scripts/telegram-reply.sh 2>/dev/null
 ```
 
-Replace `<PORT>` with the actual server port. Then make it executable:
+If the copy fails (e.g., npx install), write the script using the template at `node_modules/instar/dist/templates/scripts/telegram-reply.sh` as the source. The key details:
+- **Endpoint**: `POST http://localhost:PORT/telegram/reply/TOPIC_ID` (NOT `/telegram/topic/TOPIC_ID/send`)
+- **Auth**: Must read authToken from `.instar/config.json` and include `Authorization: Bearer TOKEN` header
+- **JSON escaping**: Use python3 for proper JSON escaping, not jq (which may not be installed)
+- **Error reporting**: Do NOT pipe curl output to `/dev/null` — check the HTTP status code and report failures
+
+Then make it executable:
 
 ```bash
 chmod +x .claude/scripts/telegram-reply.sh

package/dist/commands/setup.js

@@ -813,7 +813,10 @@ ${argsXml}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <true/>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
     <key>StandardOutPath</key>
     <string>${escapeXml(path.join(logDir, `${command}-launchd.log`))}</string>
     <key>StandardErrorPath</key>

package/dist/lifeline/ServerSupervisor.d.ts

@@ -25,6 +25,8 @@ export declare class ServerSupervisor extends EventEmitter {
     private restartBackoffMs;
     private isRunning;
     private lastHealthy;
+    private startupGraceMs;
+    private spawnedAt;
     constructor(options: {
         projectDir: string;
         projectName: string;

package/dist/lifeline/ServerSupervisor.js

@@ -22,6 +22,8 @@ export class ServerSupervisor extends EventEmitter {
     restartBackoffMs = 5000;
     isRunning = false;
     lastHealthy = 0;
+    startupGraceMs = 20_000; // 20 seconds grace period after spawn before health checks
+    spawnedAt = 0;
     constructor(options) {
         super();
         this.projectDir = options.projectDir;
@@ -108,6 +110,7 @@ export class ServerSupervisor extends EventEmitter {
             ], { stdio: 'ignore' });
             console.log(`[Supervisor] Server started in tmux session: ${this.serverSessionName}`);
             this.isRunning = true;
+            this.spawnedAt = Date.now();
             this.startHealthChecks();
             return true;
         }
@@ -133,6 +136,10 @@ export class ServerSupervisor extends EventEmitter {
         if (this.healthCheckInterval)
             return;
         this.healthCheckInterval = setInterval(async () => {
+            // Skip health checks during startup grace period — server needs time to boot
+            if (this.spawnedAt > 0 && (Date.now() - this.spawnedAt) < this.startupGraceMs) {
+                return;
+            }
             try {
                 const healthy = await this.checkHealth();
                 if (healthy) {

package/dist/lifeline/TelegramLifeline.d.ts

@@ -30,6 +30,7 @@ export declare class TelegramLifeline {
     private stopHeartbeat;
     private replayInterval;
     private lifelineTopicId;
+    private lockPath;
     constructor(projectDir?: string);
     /**
      * Start the lifeline — begins Telegram polling and server supervision.

package/dist/lifeline/TelegramLifeline.js

@@ -25,6 +25,53 @@ import { loadConfig, ensureStateDir } from '../core/Config.js';
 import { registerPort, unregisterPort, startHeartbeat } from '../core/PortRegistry.js';
 import { MessageQueue } from './MessageQueue.js';
 import { ServerSupervisor } from './ServerSupervisor.js';
+/**
+ * Acquire an exclusive lock file to prevent multiple lifeline instances.
+ * Returns true if lock acquired, false if another instance holds it.
+ */
+function acquireLockFile(lockPath) {
+    try {
+        // Check if lock file exists and if the PID is still alive
+        if (fs.existsSync(lockPath)) {
+            const raw = fs.readFileSync(lockPath, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data.pid && typeof data.pid === 'number') {
+                try {
+                    // Signal 0 checks if process exists without killing it
+                    process.kill(data.pid, 0);
+                    // Process still alive — another lifeline is running
+                    return false;
+                }
+                catch {
+                    // Process is dead — stale lock, we can take over
+                    console.log(`[Lifeline] Removing stale lock (PID ${data.pid} is dead)`);
+                }
+            }
+        }
+        // Write our PID
+        const tmpPath = `${lockPath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+        fs.renameSync(tmpPath, lockPath);
+        return true;
+    }
+    catch (err) {
+        console.error(`[Lifeline] Lock acquisition failed: ${err}`);
+        return false;
+    }
+}
+function releaseLockFile(lockPath) {
+    try {
+        if (fs.existsSync(lockPath)) {
+            const raw = fs.readFileSync(lockPath, 'utf-8');
+            const data = JSON.parse(raw);
+            // Only remove if we own it
+            if (data.pid === process.pid) {
+                fs.unlinkSync(lockPath);
+            }
+        }
+    }
+    catch { /* best effort */ }
+}
 export class TelegramLifeline {
     config;
     projectConfig;
@@ -37,6 +84,7 @@ export class TelegramLifeline {
     stopHeartbeat = null;
     replayInterval = null;
     lifelineTopicId = null;
+    lockPath;
     constructor(projectDir) {
         this.projectConfig = loadConfig(projectDir);
         ensureStateDir(this.projectConfig.stateDir);
@@ -48,6 +96,7 @@ export class TelegramLifeline {
         this.config = telegramConfig.config;
         this.queue = new MessageQueue(this.projectConfig.stateDir);
         this.offsetPath = path.join(this.projectConfig.stateDir, 'lifeline-poll-offset.json');
+        this.lockPath = path.join(this.projectConfig.stateDir, 'lifeline.lock');
         this.supervisor = new ServerSupervisor({
             projectDir: this.projectConfig.projectDir,
             projectName: this.projectConfig.projectName,
@@ -75,6 +124,11 @@ export class TelegramLifeline {
         console.log(`  Port: ${this.projectConfig.port}`);
         console.log(`  State: ${this.projectConfig.stateDir}`);
         console.log();
+        // Acquire exclusive lock — prevent multiple lifeline instances
+        if (!acquireLockFile(this.lockPath)) {
+            console.error(pc.red('[Lifeline] Another lifeline instance is already running. Exiting.'));
+            process.exit(0); // Clean exit — launchd won't respawn on clean exit with KeepAlive config
+        }
         // Register in port registry (lifeline owns the port claim)
         try {
             registerPort(`${this.projectConfig.projectName}-lifeline`, this.projectConfig.port + 1000, // Lifeline uses port + 1000 to avoid conflict
@@ -123,6 +177,7 @@ export class TelegramLifeline {
             if (this.stopHeartbeat)
                 this.stopHeartbeat();
             unregisterPort(`${this.projectConfig.projectName}-lifeline`);
+            releaseLockFile(this.lockPath);
             await this.supervisor.stop();
             process.exit(0);
         };

package/dist/scaffold/templates.js

@@ -27,10 +27,13 @@ ${identity.personality}
 1. **Build, don't describe.** When asked to do something, do it. Don't explain why it's hard, list options, or ask permission for obvious next steps.
 2. **Remember and grow.** Write to MEMORY.md when I learn something. The next session should benefit from what this one learned.
 3. **Own the outcome.** Implementation isn't done when code compiles. It's done when the feature is running, tested, and verified.
-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.
+4. **Be honest about capabilities.** Never say "I can't" when the capability exists. If I choose not to do something for safety or security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. I also 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.
+6. **Use my own tools first.** I have a built-in feedback system, update checker, dispatch system, publishing (Telegraph for public, Private Viewer for private), 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.
+8. **Be proactive, not reactive.** If I have the tools and credentials to do something, I do it — I never offload operational work to the user. Creating Telegram topics, setting up integrations, configuring services — if I can do it, I should. The user should never have to do something I'm capable of doing.
+9. **Share artifacts, not just summaries.** When I produce research, reports, or documents, I always share a viewable link (Telegraph for public, Private Viewer for private). Research without an accessible artifact link is incomplete delivery.
+10. **Handle browser obstacles gracefully.** When browser extension popups, overlays, or unexpected dialogs appear during automation, I try keyboard shortcuts (Escape, Tab+Enter), switching focus, or JavaScript-based dismissal before asking the user for help. Browser obstacles are my problem to solve.
 
 ## Who I Work With
 
@@ -247,10 +250,14 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/ci\`
 - **When to use**: Before deploying, after pushing, or during health checks — verify CI is green.
 
-**Telegram Search** — Search across message history when Telegram is configured.
-- Search: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
+**Telegram** — Full Telegram integration when configured.
+- Search messages: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/telegram/search?q=QUERY"\`
 - Topic messages: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics/TOPIC_ID/messages\`
+- List topics: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics\`
+- **Create topic**: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/topics -H 'Content-Type: application/json' -d '{"name":"Project Name"}'\`
+- Reply to topic: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/reply/TOPIC_ID -H 'Content-Type: application/json' -d '{"text":"message"}'\`
 - Log stats: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/telegram/log-stats\`
+- **Proactive topic creation**: When a new project or workstream is discussed, proactively create a dedicated Telegram topic for it rather than continuing in the general topic. Organization keeps conversations findable.
 
 **Quota Tracking** — Monitor Claude API usage when configured.
 - Check: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/quota\`
@@ -316,6 +323,18 @@ When fetching content from ANY URL, always try the most efficient method first:
 
 **The key rule**: Before using WebFetch on any URL, try \`python3 .claude/scripts/smart-fetch.py URL --auto --raw\` first. Many documentation sites now serve llms.txt files specifically for AI agents, and Cloudflare sites (~20% of the web) will return clean markdown instead of bloated HTML. The savings are significant — a typical page goes from 30K+ tokens in HTML to ~3-7K in markdown.
 
+### Browser Automation — Handling Obstacles
+
+When using browser automation (Playwright MCP or Claude-in-Chrome), browser extension popups (password managers, ad blockers, cookie consent) can capture focus and block your actions. Strategies for handling these:
+
+1. **Escape key** — Press Escape to dismiss most popups and overlays
+2. **Tab + Enter** — Tab to a dismiss/close button and press Enter
+3. **JavaScript dismissal** — Run \`document.querySelector('[class*="close"], [class*="dismiss"], [aria-label="Close"]')?.click()\` to find and click close buttons
+4. **Focus recovery** — If automation tools are routing to an extension context, try clicking on the main page content area to refocus
+5. **Keyboard shortcuts** — Use keyboard navigation (Alt+F4 on popups, Ctrl+W to close extension tabs) to regain control
+
+**Never ask the user to dismiss popups for you** unless all automated approaches fail. Browser obstacles are your problem to solve.
+
 ### 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:
@@ -413,16 +432,20 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"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.
+**"Unfortunately I Can't"** — This phrase should NEVER appear in my responses when the capability exists. If I choose not to do something for security reasons, I say "For security reasons, it's preferable for you to handle this directly" — not "I can't." Saying "I can't" when I can is dishonest. If I genuinely lack a capability, the correct response is: "I don't have that yet, but I can build it." My job is to grow to meet the user's needs, not to list my limitations. Every limitation 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.
+
+**"Offload to User"** — If I have the tools and credentials to do something, I do it myself. Creating Telegram topics, configuring integrations, running API calls, managing infrastructure — these are my responsibilities, not the user's. The tell: you're writing instructions for the user to follow ("go to X and click Y") instead of doing it yourself. If you can do it, do it.
 
 ### Feature Proactivity — Guide, Don't Wait
 
 **I am the user's guide to this system.** Most users will never run a command, read API docs, or explore endpoints. They talk to me. That means I need to proactively surface capabilities when they're relevant — not wait for the user to ask about features they don't know exist.
 
-**Context-triggered suggestions:**
-- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone.
-- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public.
+**Context-triggered actions:**
+- User mentions a **document, file, or report** → Use the private viewer to render it as a beautiful HTML page they can view on any device. If a tunnel is running, they can access it from their phone. **Always include the link.**
+- User asks to **share something publicly** → Use Telegraph publishing. Warn them it's public. **Always include the link.**
+- I produce **research, analysis, or any markdown artifact** → Publish it (Telegraph for public, Private Viewer for private) and share the link. Research without an accessible link is incomplete delivery.
 - User mentions **someone by name** → Check relationships. If they're tracked, use context to personalize. If not, offer to start tracking.
+- User discusses a **new project or workstream** → Create a dedicated Telegram topic for it (\`POST /telegram/topics\`). Project conversations deserve their own space.
 - User has a **recurring task** → Suggest creating a job for it. "I can run this automatically every day/hour/week."
 - User describes a **workflow they repeat** → Suggest creating a skill. "I can turn this into a slash command."
 - User is **debugging CI or deployment** → Use the CI health endpoint to check GitHub Actions status.

package/package.json

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