instar 1.3.207 → 1.3.208

package/dist/core/PostUpdateMigrator.js

@@ -1716,6 +1716,13 @@ export class PostUpdateMigrator {
         catch (err) {
             result.errors.push(`session-start.sh: ${err instanceof Error ? err.message : String(err)}`);
         }
+        try {
+            fs.writeFileSync(path.join(instarHooksDir, 'mcp-health-autorefresh.sh'), this.getMcpHealthAutorefreshHook(), { mode: 0o755 });
+            result.upgraded.push('hooks/instar/mcp-health-autorefresh.sh (auto-restart-on-MCP-inaccessible, dark by default)');
+        }
+        catch (err) {
+            result.errors.push(`mcp-health-autorefresh.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
         try {
             fs.writeFileSync(path.join(instarHooksDir, 'dangerous-command-guard.sh'), this.getDangerousCommandGuard(), { mode: 0o755 });
             result.upgraded.push('hooks/instar/dangerous-command-guard.sh');
@@ -5117,6 +5124,7 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
     getHookContent(name) {
         switch (name) {
             case 'session-start': return this.getSessionStartHook();
+            case 'mcp-health-autorefresh': return this.getMcpHealthAutorefreshHook();
             case 'compaction-recovery': return this.getCompactionRecovery();
             case 'external-operation-gate': return this.getExternalOperationGateHook();
             case 'deferral-detector': return this.getDeferralDetectorHook();
@@ -5144,6 +5152,109 @@ Create worktrees for collaborator repos with \`instar worktree create <branch>\`
     getConvergenceCheckPublic() {
         return this.getConvergenceCheck();
     }
+    /**
+     * mcp-health-autorefresh.sh — auto-recover from an allowlisted MCP that failed
+     * to register this session, by self-/sessions/refresh ONCE (loop-guarded).
+     *
+     * Justin's ask (2026-06-02, topic 13481): "if [an MCP is] inaccessible, you
+     * restart your session so it can be accessible in the next session. This should
+     * be AUTOMATIC, a known protocol in process." A configured MCP reporting
+     * "Failed to connect" in `claude mcp list` means its tools are missing this
+     * boot; a fresh session re-launches it and it connects on retry (proven live:
+     * playwright was unregistered, came up Connected after one /sessions/refresh).
+     *
+     * SAFETY (high blast radius — it restarts a session):
+     *  - DARK by default: only runs when config.mcpAutoRefresh.enabled === true.
+     *  - ALLOWLISTED: only refreshes for config.mcpAutoRefresh.servers (default
+     *    ["playwright"]) — an arbitrary optional MCP failing never triggers a restart.
+     *  - HARD LOOP-GUARD: a marker keyed on (sessionId, failed-set). If we already
+     *    refreshed THIS session for THIS exact failed-set, the failure is persistent
+     *    (not a transient race) → do NOT refresh again; surface instead. So it can
+     *    refresh at most ONCE per session and can NEVER restart-loop the fleet.
+     *  - Backgrounded by session-start.sh so it never blocks boot.
+     */
+    getMcpHealthAutorefreshHook() {
+        return `#!/bin/bash
+# AUTO-GENERATED by instar PostUpdateMigrator.getMcpHealthAutorefreshHook().
+# Auto-recover from an allowlisted MCP that failed to register, by a single
+# loop-guarded /sessions/refresh. DARK by default. See the method's doc comment.
+set -uo pipefail
+INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+CONFIG="\$INSTAR_DIR/config.json"
+[ -f "\$CONFIG" ] || exit 0
+
+# Enablement: explicit config.mcpAutoRefresh.enabled wins; if UNSET, a DEVELOPMENT
+# agent (config.developmentAgent === true — e.g. echo, the dogfooding ground) gets
+# it ENABLED, while production agents stay DARK. So "ships dark" means dark on the
+# fleet but live on dev agents that prove features first. Explicit false always wins.
+ENABLED=\$(python3 -c "import json;c=json.load(open('\$CONFIG'));e=c.get('mcpAutoRefresh',{}).get('enabled');print(e is True or (e is None and c.get('developmentAgent') is True))" 2>/dev/null || echo False)
+[ "\$ENABLED" = "True" ] || exit 0
+
+SESSION_ID="\${CLAUDE_CODE_SESSION_ID:-}"
+[ -n "\$SESSION_ID" ] || exit 0
+MARKER="\$INSTAR_DIR/state/mcp-autorefresh-marker.json"
+
+# Allowlist (default: playwright). Arbitrary failing MCPs must NOT trigger restarts.
+ALLOW=\$(python3 -c "import json;print(','.join(json.load(open('\$CONFIG')).get('mcpAutoRefresh',{}).get('servers',['playwright'])))" 2>/dev/null || echo playwright)
+[ -n "\$ALLOW" ] || exit 0
+
+# Resolve the claude binary (NOT always on PATH)
+CLAUDE_BIN=""
+for c in "\$(command -v claude 2>/dev/null)" /opt/homebrew/bin/claude "\$HOME"/.asdf/installs/nodejs/*/bin/claude; do
+  [ -n "\$c" ] && [ -x "\$c" ] && { CLAUDE_BIN="\$c"; break; }
+done
+[ -n "\$CLAUDE_BIN" ] || exit 0
+
+LIST=\$(timeout 45 "\$CLAUDE_BIN" mcp list 2>/dev/null || true)
+[ -n "\$LIST" ] || exit 0
+
+# Allowlisted servers reporting "Failed to connect"
+FAILED=""
+IFS=',' read -ra ALLOWED <<< "\$ALLOW"
+for s in "\${ALLOWED[@]}"; do
+  if echo "\$LIST" | grep -iE "^\${s}:" | grep -qi "Failed to connect"; then
+    FAILED="\${FAILED:+\$FAILED,}\$s"
+  fi
+done
+[ -n "\$FAILED" ] || exit 0   # all allowlisted MCPs healthy
+
+# HARD LOOP-GUARD: refresh at most ONCE per (session, failed-set).
+if [ -f "\$MARKER" ]; then
+  PREV=\$(python3 -c "import json;d=json.load(open('\$MARKER'));print(d.get('sessionId','')+'|'+d.get('failed',''))" 2>/dev/null || echo "")
+  if [ "\$PREV" = "\${SESSION_ID}|\${FAILED}" ]; then
+    echo "[mcp-autorefresh] \$FAILED still failed after one refresh this session — NOT re-refreshing (persistent, not transient)." >&2
+    exit 0
+  fi
+fi
+
+PORT=\$(python3 -c "import json;print(json.load(open('\$CONFIG')).get('port',4042))" 2>/dev/null || echo 4042)
+AUTH="\${INSTAR_AUTH_TOKEN:-}"
+
+# Resolve our own tmux session name by matching CLAUDE_CODE_SESSION_ID in /sessions
+SNAME=\$(curl -s -m 5 -H "Authorization: Bearer \$AUTH" "http://localhost:\${PORT}/sessions" 2>/dev/null | python3 -c "
+import sys,json
+sid='\$SESSION_ID'
+try:
+  d=json.load(sys.stdin); arr=d if isinstance(d,list) else d.get('sessions',[])
+  for s in arr:
+    if sid in (str(s.get('resumeUuid','')), str(s.get('id','')), str(s.get('sessionId',''))):
+      print(s.get('tmuxSession') or s.get('name') or ''); break
+except Exception:
+  pass" 2>/dev/null)
+[ -n "\$SNAME" ] || { echo "[mcp-autorefresh] could not resolve own session name — skipping refresh." >&2; exit 0; }
+
+# Write the marker BEFORE refreshing so the post-refresh boot sees it and cannot loop
+mkdir -p "\$INSTAR_DIR/state"
+NOW_ISO=\$(date -u +%FT%TZ 2>/dev/null || echo "")
+python3 -c "import json;json.dump({'sessionId':'\$SESSION_ID','failed':'\$FAILED','at':'\$NOW_ISO'},open('\$MARKER','w'))" 2>/dev/null || true
+
+curl -s -m 8 -X POST -H "Authorization: Bearer \$AUTH" -H "Content-Type: application/json" \\
+  "http://localhost:\${PORT}/sessions/refresh" \\
+  -d "{\\"sessionName\\":\\"\$SNAME\\",\\"reason\\":\\"auto: MCP(s) [\$FAILED] failed to connect — refreshing to re-register\\"}" >/dev/null 2>&1
+echo "[mcp-autorefresh] MCP(s) [\$FAILED] failed to connect -> triggered one /sessions/refresh (session \$SNAME)." >&2
+exit 0
+`;
+    }
     getSessionStartHook() {
         return `#!/bin/bash
 # Session start hook — injects identity context on session lifecycle events.
@@ -5164,6 +5275,14 @@ fi
 # For startup/resume/clear — output a compact orientation
 echo "=== SESSION START ==="
 
+# Auto-restart-on-MCP-inaccessible (DARK by default — config.mcpAutoRefresh.enabled).
+# Backgrounded so it NEVER blocks boot: if an allowlisted MCP (default playwright)
+# failed to register this boot, it self-/sessions/refresh ONCE (hard loop-guarded)
+# so a missing MCP is auto-recovered instead of being a manual blocker.
+if [ "\$EVENT" != "compact" ] && [ -x "$INSTAR_DIR/hooks/instar/mcp-health-autorefresh.sh" ]; then
+  bash "$INSTAR_DIR/hooks/instar/mcp-health-autorefresh.sh" >/dev/null 2>&1 &
+fi
+
 # Current wall-clock time — addresses Claude Code's "harness injects date, not
 # time of day" blind spot. Without this, agents say things like "it's 2am" when
 # it's actually 5:45am because they carry stale clock context from session