instar 0.24.13 → 0.24.14

package/src/templates/hooks/slack-channel-context.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# slack-channel-context.sh — UserPromptSubmit hook
+#
+# Detects [slack:CHANNEL_ID] prefix in user messages and injects
+# channel conversation history as JSON context.
+#
+# Reads from the ring buffer cache via instar server API —
+# zero Slack API calls per prompt.
+
+set -euo pipefail
+
+# Read user prompt from stdin (JSON format from Claude Code)
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('userMessage',''))" 2>/dev/null) || exit 0
+
+# Check for [slack:C...] prefix
+if [[ "$PROMPT" =~ \[slack:([A-Z0-9]+)\] ]]; then
+  CHANNEL_ID="${BASH_REMATCH[1]}"
+else
+  exit 0
+fi
+
+# Get port and auth from config
+PORT="${INSTAR_PORT:-}"
+AUTH=""
+
+if [ -f ".instar/config.json" ]; then
+  if [ -z "$PORT" ]; then
+    CONFIG_PORT=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('port',''))" 2>/dev/null)
+    [ -n "$CONFIG_PORT" ] && PORT="$CONFIG_PORT"
+  fi
+  AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+fi
+
+PORT="${PORT:-4042}"
+
+# Check server health
+if ! curl -sf "http://localhost:${PORT}/health" >/dev/null 2>&1; then
+  exit 0  # Server not running — graceful degradation
+fi
+
+# Fetch channel history from ring buffer cache
+MESSAGES=$(curl -sf \
+  ${AUTH:+-H "Authorization: Bearer $AUTH"} \
+  "http://localhost:${PORT}/slack/channels/${CHANNEL_ID}/messages?limit=30" 2>/dev/null) || exit 0
+
+# Format thread history for session context
+python3 -c "
+import json, sys
+from datetime import datetime
+
+data = json.loads('''${MESSAGES}''')
+messages = data.get('messages', [])
+
+if not messages:
+    sys.exit(0)
+
+lines = ['--- Thread History (last {} messages) ---'.format(len(messages))]
+lines.append('IMPORTANT: Read this history carefully before taking any action.')
+lines.append('Your task is to continue THIS conversation, not start something new.')
+lines.append('Topic: slack-{}'.format('${CHANNEL_ID}'))
+lines.append('')
+
+unanswered = 0
+for msg in messages:
+    ts = msg.get('ts', '')
+    try:
+        dt = datetime.fromtimestamp(float(ts))
+        time_str = dt.strftime('%H:%M:%S')
+    except:
+        time_str = ts
+
+    user = msg.get('user', 'unknown')
+    text = msg.get('text', '')
+
+    # Truncate very long messages
+    if len(text) > 2000:
+        text = text[:2000] + '...'
+
+    # Determine if from user or agent
+    sender = 'User' if msg.get('fromUser', True) else 'Agent'
+    lines.append('[{}] {}: {}'.format(time_str, sender, text))
+
+lines.append('')
+lines.append('--- End Thread History ---')
+lines.append('')
+lines.append('CRITICAL: You MUST relay your response back to Slack after responding.')
+lines.append('Use the relay script:')
+lines.append('')
+lines.append(\"cat <<'EOF' | .claude/scripts/slack-reply.sh ${CHANNEL_ID}\")
+lines.append('Your response text here')
+lines.append('EOF')
+lines.append('')
+lines.append('Strip the [slack:${CHANNEL_ID}] prefix before interpreting the message.')
+lines.append('Only relay conversational text — not tool output or internal reasoning.')
+
+print('\n'.join(lines))
+" 2>/dev/null || exit 0

package/src/templates/scripts/slack-reply.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# slack-reply.sh — Send a message to a Slack channel via the instar server.
+#
+# Usage:
+#   slack-reply.sh CHANNEL_ID "message text"
+#   echo "message" | slack-reply.sh CHANNEL_ID
+#   cat <<'EOF' | slack-reply.sh CHANNEL_ID
+#   Multi-line message here
+#   EOF
+
+set -euo pipefail
+
+CHANNEL_ID="$1"
+shift
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MESSAGE="$*"
+else
+  MESSAGE="$(cat)"
+fi
+
+if [ -z "$MESSAGE" ]; then
+  echo "Error: no message text provided" >&2
+  exit 1
+fi
+
+# Get port from env or config
+PORT="${INSTAR_PORT:-}"
+AUTH=""
+
+if [ -f ".instar/config.json" ]; then
+  if [ -z "$PORT" ]; then
+    CONFIG_PORT=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('port',''))" 2>/dev/null)
+    [ -n "$CONFIG_PORT" ] && PORT="$CONFIG_PORT"
+  fi
+  AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+fi
+
+PORT="${PORT:-4042}"
+
+# JSON-escape the message
+ESCAPED=$(python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))" <<< "$MESSAGE" 2>/dev/null)
+# Fallback to basic bash escaping if python unavailable
+if [ -z "$ESCAPED" ]; then
+  ESCAPED="\"$(echo "$MESSAGE" | sed 's/\\/\\\\/g; s/"/\\"/g')\""
+fi
+
+# Send via Instar server
+RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+  "http://localhost:${PORT}/slack/reply/${CHANNEL_ID}" \
+  -H "Content-Type: application/json" \
+  ${AUTH:+-H "Authorization: Bearer $AUTH"} \
+  -d "{\"text\": ${ESCAPED}}")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent ${#MESSAGE} chars to channel ${CHANNEL_ID}"
+else
+  echo "Failed (HTTP ${HTTP_CODE}): ${BODY}" >&2
+  exit 1
+fi

package/upgrades/0.24.11.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.24.11
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Health endpoint no longer blocks on stale sessions**: The health check previously called synchronous tmux operations for every tracked session, blocking the event loop. With many stale sessions (common after restart loops), this caused health check timeouts, which triggered MORE restarts — a death spiral. Now uses a cached session count updated asynchronously by the monitor tick.
+
+- **Startup session purge**: Before monitoring starts, the server now does a fast one-pass purge of all session records whose tmux sessions no longer exist. Uses a 1-second timeout per session to fail fast. This prevents the startup overload where the server spent all its boot time polling dead sessions.
+
+- **CoherenceMonitor suppresses known-pending updates**: When the AutoUpdater has already applied a version and a restart is pending (deferred for active sessions), the CoherenceMonitor no longer flags the version mismatch as a failure. This eliminates the race condition where both systems fought over restart decisions.
+
+## What to Tell Your User
+
+- **Stability improvement**: "The server should be much more resilient to restart loops now. Even if many sessions build up, the health check stays fast and the server won't get stuck in a crash-restart cycle. Stale sessions are cleaned up instantly on boot instead of dragging things down."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Non-blocking health endpoint | Automatic — no action needed |
+| Startup session purge | Automatic — runs on every server boot |
+| CoherenceMonitor update suppression | Automatic — no action needed |

package/upgrades/0.24.14.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.24.14
+
+## What Changed
+
+### Server Supervisor Self-Healing
+
+The ServerSupervisor now runs preflight diagnostics before every server spawn attempt. Previously, if the shadow install was missing or the node symlink was broken, the server would crash immediately on startup — and restarting via `/lifeline restart` would just repeat the same failure.
+
+Now, before each spawn, the supervisor checks and auto-repairs:
+
+- **Missing shadow install** — reinstalls via npm automatically
+- **Broken node symlink** — recreates it from available node binaries
+- **Stale lifeline locks** — removes locks older than 10 minutes
+
+This means `/lifeline restart` now actually fixes the problem instead of blindly retrying a broken state. Agents on remote machines can self-recover from common post-update failures without manual SSH intervention.
+
+## What to Tell Your User
+
+Your agent's server is now more resilient. If the server goes down due to a missing or corrupted install, the system will automatically detect and fix the issue before restarting. The /lifeline restart command in Telegram now does real recovery, not just a blind retry.
+
+## Summary of New Capabilities
+
+- **Preflight self-healing**: Server supervisor diagnoses and fixes common startup failures before each spawn
+- **Shadow install auto-repair**: Missing shadow installs are reinstalled automatically
+- **Node symlink recovery**: Broken node symlinks are recreated from available binaries
+- **Stale lock cleanup**: Old lifeline locks are removed to prevent restart deadlocks

package/upgrades/0.24.6.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — v0.24.6
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+- **PermissionRequest auto-approve hook**: Subagents spawned via the Agent tool don't inherit `--dangerously-skip-permissions` from the parent session. This caused permission prompts that blocked autonomous work. A new catch-all `PermissionRequest` hook (`auto-approve-permissions.js`) unconditionally approves all permission requests. Real safety remains in PreToolUse hooks.
+- The hook is automatically added to `settings.json` during init and on upgrade via PostUpdateMigrator.
+
+## What to Tell Your User
+
+No user-facing changes. This fix ensures autonomous sessions and subagents run without interruption.
+
+## Summary of New Capabilities
+
+- Auto-approve permissions for subagent sessions (prevents blocking on tool use prompts)

package/upgrades/0.24.7.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.24.7
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Tunnel reconnect storm fix**: Added a start mutex to TunnelManager so concurrent `start()` calls coalesce instead of racing. Sleep/wake handler now disables auto-reconnect before force-stopping the tunnel, preventing exit handlers from spawning competing reconnection chains. Previously, sleep/wake cycles could trigger dozens of concurrent tunnel reconnection attempts.
+
+- **Non-fatal crash prevention**: The uncaught exception handler no longer crashes the server for "Cannot set headers after they are sent to the client" and similar HTTP lifecycle errors. These are expected during tunnel transitions and don't affect server stability. Previously, a single double-response event would kill the entire server process.
+
+- **Lifeline startup grace period fix**: During the 3-minute startup grace period, the Lifeline now probes health optimistically. Previously, health checks were completely skipped during boot, causing incoming Telegram messages to be queued with "Server is temporarily down" even when the server was fully responsive (typically within ~10 seconds of restart).
+
+- **Queue delivery confirmation**: When queued messages are replayed after server recovery, the Lifeline now sends a per-topic confirmation ("Server recovered — your queued message has been delivered") so users know their message actually reached the session.
+
+## What to Tell Your User
+
+Server stability improvements. The server is much less likely to restart unexpectedly, and when it does restart, your messages should flow through almost immediately instead of being queued for up to 3 minutes. You'll also get a confirmation when any queued messages are delivered.
+
+## Summary of New Capabilities
+
+- Tunnel reconnection is now atomic — no more reconnect storms after sleep/wake
+- Non-fatal HTTP errors are logged as warnings instead of crashing the server
+- Messages reach sessions within seconds of a restart instead of waiting 3 minutes
+- Queued message delivery is confirmed via Telegram

package/upgrades/0.24.8.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.24.8
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Lifeline auto-restart after update**: When the server recovers from a planned update restart, the supervisor now emits an `updateApplied` event. The lifeline listens for this and self-exits after a 5-second flush delay. launchd KeepAlive respawns it with the updated shadow install binary. This ensures both the server AND lifeline always run the same version after an update.
+
+- Both restart detection paths are covered: when the supervisor reads the restart request directly, and when the ForegroundRestartWatcher consumes it first (via the planned-exit marker).
+
+## What to Tell Your User
+
+- **Seamless updates**: "Updates now apply to the entire system automatically — both the server and the Telegram connection. Previously, part of the system could run stale code after an update until the machine rebooted. Now everything picks up new code within seconds."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Lifeline auto-restart on update | Automatic — no action needed |

package/upgrades/0.24.9.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.24.9
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Restart window**: New config option to control when update restarts happen. When set, automatic restarts are deferred until the configured time window. Updates are still downloaded and applied to the shadow install immediately — only the process restart is held. Manual triggers via the API or conversational commands bypass the window.
+
+- Configurable in the agent's config at the path "updates.restartWindow" with start and end times in 24-hour local time format. Supports windows that wrap midnight (e.g., 23:00-05:00).
+
+## What to Tell Your User
+
+- **Restart window**: "I can now schedule update restarts for off-hours so they don't disrupt your workflow. Updates still download instantly, but the actual server restart waits for the quiet window. If you ever need an immediate update, just ask — manual triggers always work regardless of the window."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Restart window | Set "updates.restartWindow" in config with start/end times (e.g., "02:00"-"05:00") |

package/upgrades/NEXT.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
+<!-- Write this for the AGENT — they need to understand the system deeply. -->
+
+## What to Tell Your User
+
+<!-- Write talking points the agent should relay to their user. -->
+<!-- This should be warm, conversational, user-facing — not a changelog. -->
+<!-- Focus on what THEY can now do, not internal plumbing. -->
+<!--                                                                    -->
+<!-- PROHIBITED in this section (will fail validation):                 -->
+<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
+<!--   Inline code backtick references like silentReject: false        -->
+<!--   Fenced code blocks                                              -->
+<!--   Instructions to edit files or run commands                      -->
+<!--                                                                    -->
+<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
+<!-- The agent relays this to their user — keep it human.              -->
+
+- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| [Capability] | [Endpoint, command, or "automatic"] |