kai 0.12.5: MCP single-instance guard + demo teardown

MCP reconcile-on-start: scan .kai/mcp-session-*.json and decide per entry
  - dead PID          -> delete stale file
  - alive, parent dead -> orphan; SIGTERM + take over
  - alive, parent alive -> live sibling; refuse with a clear error
Prevents N MCP servers from stacking fsnotify watchers on the same workdir
(each server was logging its own push/skip for every event, flooding the
sync feed). Gating takeover on "parent dead" makes a kill ping-pong
impossible when two Claude windows share a repo.

Demo livesync scripts: new docs/teardown-livesync.sh kills the livesync
tmux session and any kai mcp serve whose cwd is under /tmp/demo-*.
setup-livesync.sh and layout-livesync.sh call it before rebuilding state.
Fix sed -> awk (macOS sed has no line-buffer flag) and drop SKIP events
from the sync feed so push/receive/merge aren't drowned out.

Author: jschatz1

docs/layout-livesync.sh

@@ -19,7 +19,11 @@ for d in a b c d; do
 done
 
 SESSION="livesync"
-tmux kill-session -t "$SESSION" 2>/dev/null || true
+
+# Kill any MCP servers and the tmux session from a prior demo run. Skipping
+# this leaves stale fsnotify watchers attached to /tmp/demo-* that flood the
+# sync feed with skip events.
+bash "$(dirname "$0")/teardown-livesync.sh"
 
 # ── Build the layout ─────────────────────────────────────────────────
 # Final shape:
@@ -35,64 +39,75 @@ tmux kill-session -t "$SESSION" 2>/dev/null || true
 tmux new-session -d -s "$SESSION" -x 240 -y 60 -c /tmp/demo-a
 tmux rename-window -t "$SESSION:0" livesync
 
-# Reserve the bottom ~18% for the sync feed.
-tmux split-window -v -l 18% -t "$SESSION:0" -c /tmp/demo-a
+# Capture pane IDs as we create them so we don't depend on numeric
+# indices (which shift under `pane-base-index 1` and across tmux
+# versions). Pane IDs look like "%17" and are stable.
+A=$(tmux display-message -p -t "$SESSION:0" '#{pane_id}')
+
+# Reserve the bottom ~35% for the sync feed (it's the narration track
+# of the demo — it needs to be tall enough to actually read).
+FEED=$(tmux split-window -v -l 35% -t "$A" -c /tmp/demo-a -P -F '#{pane_id}')
 
-# Top pane (now pane 0) becomes the 2×2. Pane 1 is the feed.
-tmux split-window -h -l 50% -t "$SESSION:0.0" -c /tmp/demo-b
-tmux split-window -v -l 50% -t "$SESSION:0.0" -c /tmp/demo-c
-tmux split-window -v -l 50% -t "$SESSION:0.2" -c /tmp/demo-d
+# Turn the top pane into a 2×2.
+B=$(tmux split-window -h -l 50% -t "$A" -c /tmp/demo-b -P -F '#{pane_id}')
+C=$(tmux split-window -v -l 50% -t "$A" -c /tmp/demo-c -P -F '#{pane_id}')
+D=$(tmux split-window -v -l 50% -t "$B" -c /tmp/demo-d -P -F '#{pane_id}')
 
 # Wire each agent pane: clear + show which agent + cd into its dir.
-# Pane indices after the splits above:
-#   0 = Agent A  (top-left)
-#   2 = Agent B  (top-right)
-#   3 = Agent C  (bottom-left)
-#   4 = Agent D  (bottom-right)
-#   1 = Sync feed (bottom strip)
-tmux send-keys -t "$SESSION:0.0" 'clear; printf "\033[1;31mAGENT A — backend\033[0m  (/tmp/demo-a)\n"' C-m
-tmux send-keys -t "$SESSION:0.2" 'clear; printf "\033[1;34mAGENT B — tests\033[0m    (/tmp/demo-b)\n"' C-m
-tmux send-keys -t "$SESSION:0.3" 'clear; printf "\033[1;32mAGENT C — frontend\033[0m (/tmp/demo-c)\n"' C-m
-tmux send-keys -t "$SESSION:0.4" 'clear; printf "\033[1;33mAGENT D — docs\033[0m     (/tmp/demo-d)\n"' C-m
+tmux send-keys -t "$A" 'clear; printf "\033[1;31mAGENT A — backend\033[0m  (/tmp/demo-a)\n"' C-m
+tmux send-keys -t "$B" 'clear; printf "\033[1;34mAGENT B — tests\033[0m    (/tmp/demo-b)\n"' C-m
+tmux send-keys -t "$C" 'clear; printf "\033[1;32mAGENT C — frontend\033[0m (/tmp/demo-c)\n"' C-m
+tmux send-keys -t "$D" 'clear; printf "\033[1;33mAGENT D — docs\033[0m     (/tmp/demo-d)\n"' C-m
 
 # Sync-feed pane: tail every agent's sync log, prefixed with the agent
 # letter. jq is used when available to pretty-print; otherwise raw JSONL.
-FEED_CMD=$(cat <<'EOS'
+#
+# We write the feed program to a file and exec it instead of piping the
+# whole multi-line if/then/fi block through `send-keys` — typing that
+# into an interactive shell is fragile (PS2 continuation hazards,
+# quoting interactions). A script file is parsed as a single unit.
+FEED_SCRIPT="/tmp/demo-livesync-feed.sh"
+cat >"$FEED_SCRIPT" <<'EOS'
+#!/usr/bin/env bash
 clear
 printf "\033[1mSYNC FEED\033[0m  (push/recv across all four agents)\n\n"
 TODAY=$(date +%Y-%m-%d)
 if command -v jq >/dev/null 2>&1; then
   {
     for d in a b c d; do
-      tail -F /tmp/demo-$d/.kai/sync-log/$TODAY.jsonl 2>/dev/null | \
-        sed "s/^/$d /" &
+      tail -F "/tmp/demo-$d/.kai/sync-log/$TODAY.jsonl" 2>/dev/null \
+        | awk -v p="$d " '{print p $0; fflush()}' &
     done
     wait
-  } | jq -r --unbuffered '
+  } | jq -R -r --unbuffered '
     def color(e):
-      if   e == "push"     then "\u001b[1;32m"
-      elif e == "recv"     then "\u001b[2m"
-      elif e == "merge"    then "\u001b[1;33m"
-      elif e == "conflict" then "\u001b[1;31m"
-      else                       "\u001b[0m" end;
-    def tag(l): if l=="a" then "\u001b[31mA" elif l=="b" then "\u001b[34mB"
-                elif l=="c" then "\u001b[32mC" elif l=="d" then "\u001b[33mD"
-                else l end;
-    (input_line_number|tostring) as $ln |
-    . as $line |
-    ($line | split(" ") | .[0]) as $letter |
-    ($line | .[2:] | fromjson? // {event:"(parse err)", file:$line}) as $ev |
-    "\(tag($letter))\u001b[0m \(color($ev.event))\( ($ev.timestamp // 0) / 1000 | strftime("%H:%M:%S") )  \($ev.event | ascii_upcase)  \($ev.file // "")\u001b[0m"
+      if   e == "push"     then ""
+      elif e == "receive"  then ""
+      elif e == "merge"    then ""
+      elif e == "conflict" then ""
+      else                      "" end;
+    def tag(l):
+      if   l == "a" then "A"
+      elif l == "b" then "B"
+      elif l == "c" then "C"
+      elif l == "d" then "D"
+      else l end;
+    . as $line
+    | ($line | split(" ") | .[0]) as $letter
+    | ($line | .[2:] | fromjson? // {event:"(parse err)", file:$line}) as $ev
+    | select($ev.event != "skip")
+    | "\(tag($letter)) \(color($ev.event))\(($ev.timestamp // 0) / 1000 | strftime("%H:%M:%S"))  \($ev.event | ascii_upcase)  \($ev.file // "")"
   '
 else
   for d in a b c d; do
-    tail -F /tmp/demo-$d/.kai/sync-log/$TODAY.jsonl 2>/dev/null | sed "s/^/[$d] /" &
+    tail -F "/tmp/demo-$d/.kai/sync-log/$TODAY.jsonl" 2>/dev/null \
+      | awk -v p="[$d] " '{print p $0; fflush()}' &
   done
   wait
 fi
 EOS
-)
-tmux send-keys -t "$SESSION:0.1" "$FEED_CMD" C-m
+chmod +x "$FEED_SCRIPT"
+tmux send-keys -t "$FEED" "exec bash $FEED_SCRIPT" C-m
 
 echo "Attaching to tmux session '$SESSION'…"
 echo "  Ctrl-B q  = show pane numbers"

docs/setup-livesync.sh

@@ -10,6 +10,11 @@ kai version | grep -qE '0\.(1[2-9]|[2-9][0-9])' || {
   echo "need kai >= 0.12.3"; exit 1
 }
 
+# Kill any MCP servers / tmux session left from a prior demo run. Otherwise
+# their fsnotify watchers stay attached and flood the new sync log with
+# skip-events (see docs/teardown-livesync.sh).
+bash "$(dirname "$0")/teardown-livesync.sh"
+
 rm -rf /tmp/demo-a /tmp/demo-b /tmp/demo-c /tmp/demo-d
 
 # ── Agent A's dir is the seed: init, push once, then clone for b/c/d. ──
@@ -55,9 +60,22 @@ eval "$(kai remote get origin | awk '
 FULL_URL="${URL%/}/$TENANT/$REPO"
 echo "seed published at: $FULL_URL"
 
-# ── Clone the same kai repo into /tmp/demo-{b,c,d} (working tree only). ──
+# ── Clone the same kai repo into /tmp/demo-{b,c,d}, then init a local
+# git repo in each so all four dirs are symmetric. We use --kai-only
+# because the kaicontext server doesn't serve git refs (kai push
+# uploads the snapshot, not a git remote). Each B/C/D gets an
+# independent local git history rooted at the scaffold state — fine
+# for the demo, since agents sync via kai, not git. ──
 for d in b c d; do
   kai clone "$FULL_URL" "/tmp/demo-$d" --kai-only
+  (
+    cd "/tmp/demo-$d"
+    git init -q -b main
+    git config user.email demo@demo
+    git config user.name Demo
+    git config commit.gpgsign false
+    git add -A && git commit -q -m "scaffold"
+  )
 done
 
 echo

docs/teardown-livesync.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Kills MCP servers and tmux session left over from a previous livesync demo.
+# Scoped to /tmp/demo-* so it can't touch real MCP servers you use for work.
+#
+# Called from setup-livesync.sh and layout-livesync.sh before they rebuild
+# state. Safe to run standalone: `bash docs/teardown-livesync.sh`.
+
+set -u
+
+tmux kill-session -t livesync 2>/dev/null || true
+
+# Find `kai mcp serve` processes whose cwd is inside /tmp/demo-*. We resolve
+# cwd via lsof because ps on macOS doesn't expose it. Anything outside the
+# demo dirs is left alone — a developer may have a real MCP server open.
+pids=$(pgrep -f "kai mcp serve" 2>/dev/null || true)
+for pid in $pids; do
+  cwd=$(lsof -p "$pid" -d cwd -Fn 2>/dev/null | awk '/^n/ {print substr($0,2); exit}')
+  case "$cwd" in
+    /tmp/demo-a|/tmp/demo-b|/tmp/demo-c|/tmp/demo-d|/tmp/demo-a/*|/tmp/demo-b/*|/tmp/demo-c/*|/tmp/demo-d/*)
+      kill "$pid" 2>/dev/null || true
+      ;;
+  esac
+done

kai-cli/cmd/kai/main.go

@@ -70,7 +70,7 @@ const (
 )
 
 // Version is the current kai CLI version
-var Version = "0.12.4"
+var Version = "0.12.5"
 
 // verbose enables debug output when --verbose/-v flag or KAI_VERBOSE env var is set
 var verbose bool

kai-cli/internal/mcp/server.go

@@ -15,9 +15,11 @@ import (
 	"os/exec"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
 	"sync/atomic"
+	"syscall"
 	"time"
 	"unicode"
 
@@ -211,6 +213,13 @@ func (s *Server) Serve(ctx context.Context) error {
 
 	s.registerTools(srv)
 
+	// Reconcile any stale or orphaned MCP sessions from prior runs before
+	// we take over the workdir. If a sibling session is alive and healthy,
+	// this returns an error and we refuse to start.
+	if err := s.reconcileExistingSessions(); err != nil {
+		return err
+	}
+
 	// Write MCP session file so kai capture can detect active AI sessions.
 	// The initial write uses the "mcp-client" fallback; the after-initialize
 	// hook rewrites it with the real client identity as soon as the
@@ -500,6 +509,96 @@ func (s *Server) removeSessionFile() {
 	os.Remove(s.sessionFilePath())
 }
 
+// reconcileExistingSessions handles any other MCP session files present in
+// s.kaiDir before we start watching files. Running multiple MCP servers in
+// the same workdir causes every one of them to attach a separate fsnotify
+// watcher and log its own push/skip for every event — the sync feed fills
+// with noise.
+//
+// For each stale session file we find:
+//
+//   - If the PID is dead → leftover from a prior crash. Delete the file.
+//   - If the PID is alive and its parent is dead → the parent Claude exited
+//     without taking its MCP child with it. Safe to take over: SIGTERM the
+//     orphan and delete its session file.
+//   - If the PID is alive and its parent is also alive → a legitimate
+//     concurrent Claude session is running here. Refuse to start so we
+//     don't fight over fsnotify events (and so we don't enter a ping-pong
+//     kill loop where each MCP kills the other on restart).
+//
+// The "parent alive" check is what makes this safe: once an MCP is
+// orphaned we take over permanently; once a real sibling exists, we
+// always refuse. There's no state that flips back and forth.
+func (s *Server) reconcileExistingSessions() error {
+	entries, err := os.ReadDir(s.kaiDir)
+	if err != nil {
+		return nil
+	}
+	myPid := os.Getpid()
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		if !strings.HasPrefix(name, "mcp-session-") || !strings.HasSuffix(name, ".json") {
+			continue
+		}
+		pidStr := strings.TrimSuffix(strings.TrimPrefix(name, "mcp-session-"), ".json")
+		pid, convErr := strconv.Atoi(pidStr)
+		if convErr != nil || pid == myPid {
+			continue
+		}
+		path := filepath.Join(s.kaiDir, name)
+
+		if !processAlive(pid) {
+			os.Remove(path)
+			continue
+		}
+
+		ppid, ok := parentPID(pid)
+		if !ok || !processAlive(ppid) {
+			// Orphan — parent Claude is gone. Take over.
+			_ = syscall.Kill(pid, syscall.SIGTERM)
+			os.Remove(path)
+			continue
+		}
+
+		// Live sibling. Refuse to start; let the user pick which Claude to close.
+		return fmt.Errorf("another MCP server is already running in %s (pid %d, parent pid %d). "+
+			"Close one of the Claude sessions for this workdir, or kill pid %d, then retry",
+			s.workDir, pid, ppid, pid)
+	}
+	return nil
+}
+
+// processAlive returns true if a signal-0 kill succeeds (process exists
+// and we can signal it). A "permission denied" errno also means the
+// process exists (just owned by someone else), which is treated as alive.
+func processAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	err := syscall.Kill(pid, 0)
+	if err == nil {
+		return true
+	}
+	return err == syscall.EPERM
+}
+
+// parentPID returns the PPID of pid via `ps`. Portable across macOS and
+// Linux without pulling in platform-specific sysctl code.
+func parentPID(pid int) (int, bool) {
+	out, err := exec.Command("ps", "-o", "ppid=", "-p", strconv.Itoa(pid)).Output()
+	if err != nil {
+		return 0, false
+	}
+	ppid, err := strconv.Atoi(strings.TrimSpace(string(out)))
+	if err != nil {
+		return 0, false
+	}
+	return ppid, true
+}
+
 // Close cleans up resources.
 func (s *Server) Close() error {
 	s.mu.Lock()