From ef51a5a944ffdee2cc7441a4d1ecdf70d153c0dc Mon Sep 17 00:00:00 2001
From: z3knayr0 <6465184+z3knayr0@users.noreply.github.com>
Date: Thu, 23 Jul 2026 13:04:55 -0500
Subject: [PATCH] Add multi-session support: multiple agents in the same repo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Session identity was keyed by project directory (a single
.claude/bridge-session pointer per repo), so a second agent session in
the same repo reused the first session's ID — same-repo peers could not
address each other, and one session's cleanup could destroy the other's
bridge state.

- New get-session-key.sh: stable per-agent-session key (BRIDGE_SESSION_KEY
  env override, else first non-shell ancestor PID)
- register.sh: per-session pointers at .claude/bridge-sessions/<key>;
  optional --as <label> (defaults to git branch) stored in the manifest;
  legacy .claude/bridge-session no longer written
- get-session-id.sh: env -> per-session pointer (walks up from cwd) ->
  legacy pointer -> path scan
- cleanup.sh: removes only the calling session's own dir and pointer
- Labels surfaced everywhere: list-peers LABEL column, message metadata
  fromLabel, FROM_LABEL in bridge-listen, labeled bridge-receive output,
  label in connect-peer output
- heartbeat.sh resolves via get-session-id.sh
- Docs updated (bridge.md, SKILL.md, README); tests updated for the new
  pointer layout; new test-same-repo.sh end-to-end coverage
- Full suite: 183 tests passing (was 132)
---
 README.md                                     |  18 ++-
 plugins/session-bridge/commands/bridge.md     |  26 ++--
 .../session-bridge/scripts/bridge-listen.sh   |   2 +
 .../session-bridge/scripts/bridge-receive.sh  |   7 +-
 plugins/session-bridge/scripts/cleanup.sh     |  69 ++++++++--
 .../session-bridge/scripts/connect-peer.sh    |   7 +-
 .../session-bridge/scripts/get-session-id.sh  |  47 +++++--
 .../session-bridge/scripts/get-session-key.sh |  35 +++++
 plugins/session-bridge/scripts/heartbeat.sh   |  12 +-
 plugins/session-bridge/scripts/list-peers.sh  |   7 +-
 plugins/session-bridge/scripts/register.sh    |  75 +++++++---
 .../session-bridge/scripts/send-message.sh    |   8 +-
 .../skills/bridge-awareness/SKILL.md          |   9 +-
 plugins/session-bridge/tests/test-cleanup.sh  |  23 ++--
 .../tests/test-get-session-id.sh              |  22 ++-
 .../session-bridge/tests/test-heartbeat.sh    |   8 +-
 .../session-bridge/tests/test-integration.sh  |   9 +-
 plugins/session-bridge/tests/test-register.sh |  51 ++++++-
 .../session-bridge/tests/test-same-repo.sh    | 130 ++++++++++++++++++
 19 files changed, 465 insertions(+), 100 deletions(-)
 create mode 100644 plugins/session-bridge/scripts/get-session-key.sh
 create mode 100644 plugins/session-bridge/tests/test-same-repo.sh

diff --git a/README.md b/README.md
index 117fa06..1476f2d 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,7 @@ That's it. The Library agent responds with its **full session context** — it k
 
 | Command | Description |
 |---------|-------------|
-| `/bridge start` | Register this session as a bridge peer |
+| `/bridge start [--as <label>]` | Register this session as a bridge peer (label defaults to the git branch) |
 | `/bridge connect <id>` | Connect to a peer session (auto-starts if needed) |
 | `/bridge listen` | Enter listening mode — answer peer queries continuously |
 | `/bridge ask <question>` | Send a question and wait for the response |
@@ -120,6 +120,10 @@ The key innovation: `/bridge listen` puts the agent into a **continuous listenin
 - UUID message IDs — no collision risk
 - Connection via ping handshake — peers never mutate each other's manifests
 
+### Multiple sessions in the same repo
+
+Session identity is keyed by the agent session (a per-session pointer derived from the agent process), not the project directory — so two Claude Code sessions in the same repo each get their own bridge identity. They're distinguished by their **label** (the git branch by default, or `--as <label>`) and session ID in `/bridge peers`. `/bridge stop` only cleans up the calling session's own state.
+
 ---
 
 ## When To Use It
@@ -191,11 +195,11 @@ Consumer user: "Ask the backend team what the new API response format looks like
 
 ```
 > /bridge peers
-SESSION    PROJECT              STATUS   PATH
--------    -------              ------   ----
-a1b2c3     auth-sdk             active   ~/projects/auth-sdk
-d4e5f6     payments-service     active   ~/projects/payments
-g7h8i9     my-app               active   ~/projects/my-app  (you)
+SESSION    PROJECT              LABEL          STATUS   PATH
+-------    -------              -----          ------   ----
+a1b2c3     auth-sdk             main           active   ~/projects/auth-sdk
+d4e5f6     payments-service     main           active   ~/projects/payments
+g7h8i9     my-app               feature/login  active   ~/projects/my-app  (you)
 
 > /bridge ask "What config format does the payments service expect?"
   Routes to payments-service peer automatically based on question context
@@ -261,6 +265,8 @@ plugins/session-bridge/
 │       └── SKILL.md             # Teaches agent the bridge protocol
 ├── scripts/
 │   ├── register.sh              # Create session directory and manifest
+│   ├── get-session-id.sh        # Resolve this session's ID
+│   ├── get-session-key.sh       # Resolve stable per-agent-session key
 │   ├── send-message.sh          # Send message to peer's inbox
 │   ├── check-inbox.sh           # Scan inboxes for pending messages
 │   ├── list-peers.sh            # List active sessions
diff --git a/plugins/session-bridge/commands/bridge.md b/plugins/session-bridge/commands/bridge.md
index 72ddfe3..6c8ebf4 100644
--- a/plugins/session-bridge/commands/bridge.md
+++ b/plugins/session-bridge/commands/bridge.md
@@ -30,15 +30,22 @@ Register this session as a bridge peer.
    ```bash
    bash "${CLAUDE_PLUGIN_ROOT}/scripts/register.sh"
    ```
-2. Capture the session ID from stdout.
+   Optionally pass a label to identify this session to peers (defaults to the current git branch):
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/scripts/register.sh" --as frontend
+   ```
+2. Capture the session ID from stdout. The label is the `--as` value if given, otherwise the current git branch (empty outside a git repo).
 3. Display to the user:
    ```
    Bridge active!
    Session ID: <session-id>
+   Label: <label>
    Share this ID with other Claude sessions to connect: /bridge connect <session-id>
    Use /bridge listen to start receiving and answering peer queries.
    ```
 
+**Multiple sessions in the same repo are supported.** Each agent session registers independently and is distinguished by its label (git branch by default, or `--as <label>`). Use distinct labels — e.g. `/bridge start --as frontend` and `/bridge start --as backend` — so peers can tell same-repo sessions apart.
+
 ### `connect <session-id>`
 
 Connect to a peer session. Auto-starts this session's bridge if not already active.
@@ -87,7 +94,7 @@ The loop:
    bash "${CLAUDE_PLUGIN_ROOT}/scripts/bridge-listen.sh" "$MY_SESSION"
    ```
 3. When a message arrives, parse the output:
-   - Lines before `---` are metadata (MESSAGE_ID, FROM_ID, TO_ID, FROM_PROJECT, TYPE, IN_REPLY_TO)
+   - Lines before `---` are metadata (MESSAGE_ID, FROM_ID, TO_ID, FROM_PROJECT, FROM_LABEL, TYPE, IN_REPLY_TO)
    - Lines after `---` are the message content
 
 4. Handle by message type. **Use `TO_ID` from the message metadata as your session ID** when sending responses. This is always correct regardless of working directory.
@@ -123,7 +130,7 @@ Send a query to a connected peer and wait for the response.
    ```bash
    find ~/.claude/session-bridge/sessions/$MY_SESSION/inbox -name "*.json" -exec jq -r 'select(.type == "ping") | .from' {} \; 2>/dev/null | sort -u
    ```
-3. If multiple peers, ask which one to query.
+3. If multiple peers, pick the most relevant one by label first, then project name (several sessions may share one project). Ask the user if still ambiguous.
 4. Send the query and capture the message ID:
    ```bash
    MSG_ID=$(BRIDGE_SESSION_ID=$MY_SESSION bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" "<peer-id>" query "<question>")
@@ -144,7 +151,7 @@ List all active bridge sessions on this machine.
    ```bash
    bash "${CLAUDE_PLUGIN_ROOT}/scripts/list-peers.sh"
    ```
-2. Display the formatted table.
+2. Display the formatted table — its LABEL column shows each session's label (git branch by default, or the `--as` value), which together with the session ID distinguishes multiple sessions in the same repo.
 3. To highlight which one is "you", run:
    ```bash
    bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-session-id.sh"
@@ -159,7 +166,7 @@ Show current bridge state.
    MY_SESSION=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-session-id.sh")
    ```
    If it fails, say "Bridge is not active. Run `/bridge start` to begin."
-2. Display the session ID.
+2. Display the session ID and label (shown in the manifest and in `/bridge peers`).
 3. List connected peers (from ping messages in inbox).
 4. Count pending (unread) messages in inbox.
 5. Count messages in outbox (sent).
@@ -167,10 +174,11 @@ Show current bridge state.
    ```
    Bridge Status
    Session ID: abc123
+   Label: frontend
    Project: my-app
 
    Connected Peers:
-   - my-library (def456) - active
+   - backend (def456) - active
 
    Inbox: 2 pending messages
    Outbox: 5 messages sent
@@ -178,7 +186,7 @@ Show current bridge state.
 
 ### `stop`
 
-Unregister and clean up.
+Unregister and clean up. This only removes THIS session's own bridge state — other sessions in the same repo (or elsewhere) keep running.
 
 1. Run:
    ```bash
@@ -191,11 +199,11 @@ Unregister and clean up.
 If no argument is given, show a brief help:
 ```
 Bridge commands:
-  /bridge start              - Register this session
+  /bridge start [--as label] - Register this session (label defaults to git branch)
   /bridge connect <id>       - Connect to a peer session
   /bridge listen             - Listen and answer peer queries (blocks)
   /bridge ask <question>     - Send a question to a peer
-  /bridge peers              - List active sessions
+  /bridge peers              - List active sessions (with labels)
   /bridge status             - Show bridge state
   /bridge stop               - Disconnect and clean up
 ```
diff --git a/plugins/session-bridge/scripts/bridge-listen.sh b/plugins/session-bridge/scripts/bridge-listen.sh
index 2828891..1f676a3 100755
--- a/plugins/session-bridge/scripts/bridge-listen.sh
+++ b/plugins/session-bridge/scripts/bridge-listen.sh
@@ -52,6 +52,7 @@ while true; do
     MSG_TYPE=$(jq -r '.type' "$MSG_FILE")
     CONTENT=$(jq -r '.content' "$MSG_FILE")
     FROM_PROJECT=$(jq -r '.metadata.fromProject // "unknown"' "$MSG_FILE")
+    FROM_LABEL=$(jq -r '.metadata.fromLabel // ""' "$MSG_FILE")
     IN_REPLY_TO=$(jq -r '.inReplyTo // ""' "$MSG_FILE")
 
     # Skip messages FROM ourselves (echo prevention)
@@ -69,6 +70,7 @@ while true; do
     echo "FROM_ID=$FROM_ID"
     echo "TO_ID=$TO_ID"
     echo "FROM_PROJECT=$FROM_PROJECT"
+    echo "FROM_LABEL=$FROM_LABEL"
     echo "TYPE=$MSG_TYPE"
     echo "IN_REPLY_TO=$IN_REPLY_TO"
     echo "---"
diff --git a/plugins/session-bridge/scripts/bridge-receive.sh b/plugins/session-bridge/scripts/bridge-receive.sh
index ff1c899..e5718b2 100755
--- a/plugins/session-bridge/scripts/bridge-receive.sh
+++ b/plugins/session-bridge/scripts/bridge-receive.sh
@@ -27,6 +27,7 @@ while [ "$ELAPSED" -lt "$TIMEOUT" ]; do
     # Found an unread response!
     CONTENT=$(jq -r '.content' "$MSG_FILE")
     FROM_PROJECT=$(jq -r '.metadata.fromProject // "unknown"' "$MSG_FILE")
+    FROM_LABEL=$(jq -r '.metadata.fromLabel // ""' "$MSG_FILE")
     MSG_TYPE=$(jq -r '.type' "$MSG_FILE")
 
     # Mark as read
@@ -34,7 +35,11 @@ while [ "$ELAPSED" -lt "$TIMEOUT" ]; do
     jq '.status = "read"' "$MSG_FILE" > "$TMP"
     mv "$TMP" "$MSG_FILE"
 
-    echo "Response from $FROM_PROJECT:"
+    if [ -n "$FROM_LABEL" ]; then
+      echo "Response from $FROM_PROJECT [$FROM_LABEL]:"
+    else
+      echo "Response from $FROM_PROJECT:"
+    fi
     echo "$CONTENT"
     exit 0
   done
diff --git a/plugins/session-bridge/scripts/cleanup.sh b/plugins/session-bridge/scripts/cleanup.sh
index dc2b644..4df651f 100755
--- a/plugins/session-bridge/scripts/cleanup.sh
+++ b/plugins/session-bridge/scripts/cleanup.sh
@@ -1,25 +1,57 @@
 #!/usr/bin/env bash
 # scripts/cleanup.sh — Clean up session on exit. Notify connected peers.
+#
+# Multi-session aware: resolves THIS agent session's bridge session ID only
+# (never a same-repo peer's), notifies its connected peers, removes only its
+# own session dir and pointer files, then sweeps stale sessions.
 set -euo pipefail
 
 BRIDGE_DIR="${BRIDGE_DIR:-$HOME/.claude/session-bridge}"
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
-BRIDGE_SESSION_FILE="$PROJECT_DIR/.claude/bridge-session"
+LEGACY_POINTER="$PROJECT_DIR/.claude/bridge-session"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Find session ID
+SESSION_KEY=$(bash "$SCRIPT_DIR/get-session-key.sh")
+POINTER_FILE="$PROJECT_DIR/.claude/bridge-sessions/$SESSION_KEY"
+
+# Find THIS agent session's bridge session ID only — never a same-repo peer's.
+# Priority: (a) env override, (b) per-session pointer (walk up from
+# PROJECT_DIR, validating the manifest), (c) legacy single pointer,
+# (d) manifest scan for projectPath == PROJECT_DIR.
 SESSION_ID=""
-if [ -f "$BRIDGE_SESSION_FILE" ]; then
-  SESSION_ID=$(cat "$BRIDGE_SESSION_FILE")
+if [ -n "${BRIDGE_SESSION_ID:-}" ] && [ -f "$BRIDGE_DIR/sessions/$BRIDGE_SESSION_ID/manifest.json" ]; then
+  SESSION_ID="$BRIDGE_SESSION_ID"
 else
-  for MANIFEST_FILE in "$BRIDGE_DIR"/sessions/*/manifest.json; do
-    [ -f "$MANIFEST_FILE" ] || continue
-    MANIFEST_PATH=$(jq -r '.projectPath // ""' "$MANIFEST_FILE" 2>/dev/null)
-    if [ "$MANIFEST_PATH" = "$PROJECT_DIR" ]; then
-      SESSION_ID=$(jq -r '.sessionId' "$MANIFEST_FILE")
-      break
+  DIR="$PROJECT_DIR"
+  while true; do
+    POINTER="$DIR/.claude/bridge-sessions/$SESSION_KEY"
+    if [ -f "$POINTER" ]; then
+      SID=$(cat "$POINTER")
+      if [ -f "$BRIDGE_DIR/sessions/$SID/manifest.json" ]; then
+        SESSION_ID="$SID"
+        POINTER_FILE="$POINTER"
+        break
+      fi
     fi
+    [ "$DIR" = "/" ] && break
+    DIR=$(dirname "$DIR")
   done
+  if [ -z "$SESSION_ID" ] && [ -f "$LEGACY_POINTER" ]; then
+    SID=$(cat "$LEGACY_POINTER")
+    if [ -f "$BRIDGE_DIR/sessions/$SID/manifest.json" ]; then
+      SESSION_ID="$SID"
+    fi
+  fi
+  if [ -z "$SESSION_ID" ]; then
+    for MANIFEST_FILE in "$BRIDGE_DIR"/sessions/*/manifest.json; do
+      [ -f "$MANIFEST_FILE" ] || continue
+      MANIFEST_PATH=$(jq -r '.projectPath // ""' "$MANIFEST_FILE" 2>/dev/null)
+      if [ "$MANIFEST_PATH" = "$PROJECT_DIR" ]; then
+        SESSION_ID=$(jq -r '.sessionId' "$MANIFEST_FILE")
+        break
+      fi
+    done
+  fi
 fi
 
 if [ -z "$SESSION_ID" ]; then
@@ -45,15 +77,24 @@ PEER_IDS=$(echo "$PEER_IDS" | tr ' ' '\n' | sort -u | grep -v '^$' || true)
 for PEER_ID in $PEER_IDS; do
   if [ -d "$BRIDGE_DIR/sessions/$PEER_ID/inbox" ]; then
     BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_ID="$SESSION_ID" \
-      bash "$SCRIPT_DIR/send-message.sh" "$PEER_ID" session-ended "Session ended" 2>/dev/null || true
+      bash "$SCRIPT_DIR/send-message.sh" "$PEER_ID" session-ended "Session ended" > /dev/null 2>&1 || true
   fi
 done
 
-# Remove session directory
+# Remove only the caller's own session directory
 rm -rf "$SESSION_DIR"
 
-# Remove bridge-session pointer
-rm -f "$BRIDGE_SESSION_FILE"
+# Remove only the caller's own per-session pointer (a same-repo peer has its
+# own pointer file under bridge-sessions/ — leave those alone)
+if [ -f "$POINTER_FILE" ] && [ "$(cat "$POINTER_FILE")" = "$SESSION_ID" ]; then
+  rm -f "$POINTER_FILE"
+fi
+
+# Remove the legacy pointer only if it points at OUR session (a same-repo
+# peer may have written its own ID there before migrating)
+if [ -f "$LEGACY_POINTER" ] && [ "$(cat "$LEGACY_POINTER")" = "$SESSION_ID" ]; then
+  rm -f "$LEGACY_POINTER"
+fi
 
 # Clean up stale sessions (heartbeat older than 30 minutes)
 STALE_CUTOFF=$(date -u -v-30M +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "30 minutes ago" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
diff --git a/plugins/session-bridge/scripts/connect-peer.sh b/plugins/session-bridge/scripts/connect-peer.sh
index 1f2fb33..d15dca2 100755
--- a/plugins/session-bridge/scripts/connect-peer.sh
+++ b/plugins/session-bridge/scripts/connect-peer.sh
@@ -16,6 +16,7 @@ fi
 
 PEER_NAME=$(jq -r '.projectName' "$TARGET_MANIFEST")
 PEER_PATH=$(jq -r '.projectPath' "$TARGET_MANIFEST")
+PEER_LABEL=$(jq -r '.label // ""' "$TARGET_MANIFEST")
 
 # Check for staleness (>5 min since last heartbeat)
 PEER_HB=$(jq -r '.lastHeartbeat' "$TARGET_MANIFEST")
@@ -30,4 +31,8 @@ fi
 BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_ID="$SENDER_ID" \
   bash "$SCRIPT_DIR/send-message.sh" "$TARGET_ID" ping "connected" > /dev/null
 
-echo "Connected to '$PEER_NAME' ($TARGET_ID) at $PEER_PATH"
+if [ -n "$PEER_LABEL" ]; then
+  echo "Connected to '$PEER_NAME' ($TARGET_ID) [$PEER_LABEL] at $PEER_PATH"
+else
+  echo "Connected to '$PEER_NAME' ($TARGET_ID) at $PEER_PATH"
+fi
diff --git a/plugins/session-bridge/scripts/get-session-id.sh b/plugins/session-bridge/scripts/get-session-id.sh
index 6059343..5a03506 100755
--- a/plugins/session-bridge/scripts/get-session-id.sh
+++ b/plugins/session-bridge/scripts/get-session-id.sh
@@ -1,26 +1,55 @@
 #!/usr/bin/env bash
-# scripts/get-session-id.sh — Reliably find this project's bridge session ID.
+# scripts/get-session-id.sh — Reliably find THIS agent session's bridge session ID.
 # Works even if the agent cd'd into a subdirectory.
 #
 # Strategy:
-# 1. Try .claude/bridge-session in current directory (fast path)
-# 2. Scan all session manifests for one whose projectPath is a parent of $(pwd)
+# 1. $BRIDGE_SESSION_ID env, if it points to a live session
+# 2. Per-session pointer .claude/bridge-sessions/<session-key>, walking up from cwd
+# 3. Legacy single pointer .claude/bridge-session in cwd (pre-multisession installs)
+# 4. Scan all session manifests for one whose projectPath is a parent of $(pwd)
+#    (ambiguous when several sessions share a repo — used only as a last resort)
 #
 # Outputs: session ID to stdout, or exits 1 if not found.
 set -euo pipefail
 
 BRIDGE_DIR="${BRIDGE_DIR:-$HOME/.claude/session-bridge}"
 CURRENT_DIR="${PROJECT_DIR:-$(pwd)}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Fast path: .claude/bridge-session in current directory
-if [ -f "$CURRENT_DIR/.claude/bridge-session" ]; then
-  cat "$CURRENT_DIR/.claude/bridge-session"
+# 1. Env override (written to CLAUDE_ENV_FILE at register time)
+if [ -n "${BRIDGE_SESSION_ID:-}" ] && [ -f "$BRIDGE_DIR/sessions/$BRIDGE_SESSION_ID/manifest.json" ]; then
+  echo -n "$BRIDGE_SESSION_ID"
   exit 0
 fi
 
-# Fallback: scan all session manifests for one whose projectPath is a parent of current dir.
-# e.g., if we're at /projects/my-lib/src/main/kotlin and a session has
-# projectPath=/projects/my-lib, that's a match.
+# 2. Per-session pointer, walking up from cwd to find the project root
+SESSION_KEY=$(bash "$SCRIPT_DIR/get-session-key.sh")
+DIR="$CURRENT_DIR"
+while true; do
+  POINTER="$DIR/.claude/bridge-sessions/$SESSION_KEY"
+  if [ -f "$POINTER" ]; then
+    SID=$(cat "$POINTER")
+    if [ -f "$BRIDGE_DIR/sessions/$SID/manifest.json" ]; then
+      echo -n "$SID"
+      exit 0
+    fi
+  fi
+  [ "$DIR" = "/" ] && break
+  DIR=$(dirname "$DIR")
+done
+
+# 3. Legacy single pointer in cwd (backwards compatibility)
+if [ -f "$CURRENT_DIR/.claude/bridge-session" ]; then
+  SID=$(cat "$CURRENT_DIR/.claude/bridge-session")
+  if [ -f "$BRIDGE_DIR/sessions/$SID/manifest.json" ]; then
+    echo -n "$SID"
+    exit 0
+  fi
+fi
+
+# 4. Fallback: scan all session manifests for one whose projectPath is a parent
+# of current dir. With multiple sessions in one repo this is ambiguous — the
+# per-session pointer above is the reliable path.
 for MANIFEST in "$BRIDGE_DIR"/sessions/*/manifest.json; do
   [ -f "$MANIFEST" ] || continue
   PROJ_PATH=$(jq -r '.projectPath // ""' "$MANIFEST" 2>/dev/null)
diff --git a/plugins/session-bridge/scripts/get-session-key.sh b/plugins/session-bridge/scripts/get-session-key.sh
new file mode 100644
index 0000000..de1acab
--- /dev/null
+++ b/plugins/session-bridge/scripts/get-session-key.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# scripts/get-session-key.sh — Resolve a stable key identifying the CALLING agent
+# session (not the project). Two agent sessions in the same repo get different
+# keys; repeated calls from the same agent session get the same key.
+#
+# Priority:
+# 1. $BRIDGE_SESSION_KEY env (explicit override — useful for tests and power users)
+# 2. First non-shell ancestor process PID. Inside an agent CLI (e.g. Claude Code),
+#    tool commands run as descendants of the CLI process, so this PID is stable
+#    for the lifetime of that session and distinct across sessions.
+# 3. Own PID as a last resort (no stable identity available).
+#
+# Outputs: session key to stdout (e.g. "pid12345" or the override verbatim)
+set -euo pipefail
+
+if [ -n "${BRIDGE_SESSION_KEY:-}" ]; then
+  echo -n "$BRIDGE_SESSION_KEY"
+  exit 0
+fi
+
+PID=$$
+while true; do
+  PID=$(ps -o ppid= -p "$PID" 2>/dev/null | tr -d ' ')
+  if [ -z "$PID" ] || [ "$PID" = "0" ] || [ "$PID" = "1" ]; then
+    break
+  fi
+  COMM=$(ps -o comm= -p "$PID" 2>/dev/null || echo "")
+  case "$(basename "$COMM")" in
+    bash|zsh|sh|dash|fish|env) ;;  # skip shells — the agent CLI is above them
+    *) echo -n "pid$PID"; exit 0 ;;
+  esac
+done
+
+# Fallback: no identifiable ancestor
+echo -n "pid$$"
diff --git a/plugins/session-bridge/scripts/heartbeat.sh b/plugins/session-bridge/scripts/heartbeat.sh
index 4c6eca1..2694e38 100755
--- a/plugins/session-bridge/scripts/heartbeat.sh
+++ b/plugins/session-bridge/scripts/heartbeat.sh
@@ -4,14 +4,12 @@ set -euo pipefail
 
 BRIDGE_DIR="${BRIDGE_DIR:-$HOME/.claude/session-bridge}"
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-if [ -n "${BRIDGE_SESSION_ID:-}" ]; then
-  SESSION_ID="$BRIDGE_SESSION_ID"
-elif [ -f "$PROJECT_DIR/.claude/bridge-session" ]; then
-  SESSION_ID=$(cat "$PROJECT_DIR/.claude/bridge-session")
-else
-  exit 0
-fi
+# Resolve this agent session's ID via the shared resolver; nothing to do if none
+SESSION_ID=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_DIR" \
+  bash "$SCRIPT_DIR/get-session-id.sh" 2>/dev/null || echo "")
+[ -n "$SESSION_ID" ] || exit 0
 
 MANIFEST="$BRIDGE_DIR/sessions/$SESSION_ID/manifest.json"
 [ -f "$MANIFEST" ] || exit 0
diff --git a/plugins/session-bridge/scripts/list-peers.sh b/plugins/session-bridge/scripts/list-peers.sh
index ec90bf4..7500350 100755
--- a/plugins/session-bridge/scripts/list-peers.sh
+++ b/plugins/session-bridge/scripts/list-peers.sh
@@ -15,8 +15,8 @@ NOW_EPOCH=$(date -u +%s)
 STALE_SECONDS=300  # 5 minutes
 FOUND=0
 
-printf "%-10s %-20s %-8s %s\n" "SESSION" "PROJECT" "STATUS" "PATH"
-printf "%-10s %-20s %-8s %s\n" "-------" "-------" "------" "----"
+printf "%-10s %-20s %-14s %-8s %s\n" "SESSION" "PROJECT" "LABEL" "STATUS" "PATH"
+printf "%-10s %-20s %-14s %-8s %s\n" "-------" "-------" "-----" "------" "----"
 
 for MANIFEST in "$SESSIONS_DIR"/*/manifest.json; do
   [ -f "$MANIFEST" ] || continue
@@ -24,6 +24,7 @@ for MANIFEST in "$SESSIONS_DIR"/*/manifest.json; do
   SID=$(jq -r '.sessionId' "$MANIFEST")
   PNAME=$(jq -r '.projectName' "$MANIFEST")
   PPATH=$(jq -r '.projectPath' "$MANIFEST")
+  LABEL=$(jq -r '.label // ""' "$MANIFEST")
   HB=$(jq -r '.lastHeartbeat' "$MANIFEST")
 
   # Calculate staleness (macOS date parsing — use -u to match UTC timestamps)
@@ -36,7 +37,7 @@ for MANIFEST in "$SESSIONS_DIR"/*/manifest.json; do
     STATUS="active"
   fi
 
-  printf "%-10s %-20s %-8s %s\n" "$SID" "$PNAME" "$STATUS" "$PPATH"
+  printf "%-10s %-20s %-14s %-8s %s\n" "$SID" "$PNAME" "$LABEL" "$STATUS" "$PPATH"
   FOUND=$((FOUND + 1))
 done
 
diff --git a/plugins/session-bridge/scripts/register.sh b/plugins/session-bridge/scripts/register.sh
index 603592a..2406c31 100755
--- a/plugins/session-bridge/scripts/register.sh
+++ b/plugins/session-bridge/scripts/register.sh
@@ -1,8 +1,14 @@
 #!/usr/bin/env bash
 # scripts/register.sh — Register this session as a bridge peer.
+# Usage: register.sh [--as <label>]
 # Env: BRIDGE_DIR (default: ~/.claude/session-bridge), PROJECT_DIR (default: pwd)
+#      BRIDGE_SESSION_KEY (override session identity), BRIDGE_LABEL (peer label)
 # Outputs: session ID to stdout
-# If a bridge session already exists for this project, reuses it.
+#
+# Sessions are keyed by AGENT SESSION, not by project directory: each agent
+# session gets its own pointer in .claude/bridge-sessions/<session-key>, so two
+# agents working in the same repo register as distinct peers. Re-registering
+# from the same agent session reuses its existing bridge session.
 set -euo pipefail
 
 command -v jq >/dev/null 2>&1 || { echo "Error: jq is required. Install with: brew install jq (macOS) or apt install jq (Linux)" >&2; exit 1; }
@@ -10,24 +16,47 @@ command -v jq >/dev/null 2>&1 || { echo "Error: jq is required. Install with: br
 BRIDGE_DIR="${BRIDGE_DIR:-$HOME/.claude/session-bridge}"
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 PROJECT_NAME=$(basename "$PROJECT_DIR")
-BRIDGE_SESSION_FILE="$PROJECT_DIR/.claude/bridge-session"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Reuse existing session if the bridge-session file exists and points to a valid session
-if [ -f "$BRIDGE_SESSION_FILE" ]; then
-  EXISTING_ID=$(cat "$BRIDGE_SESSION_FILE")
+LABEL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --as) LABEL="${2:?--as requires a label}"; shift 2 ;;
+    --as=*) LABEL="${1#--as=}"; shift ;;
+    *) echo "Unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+LABEL="${LABEL:-${BRIDGE_LABEL:-}}"
+
+SESSION_KEY=$(bash "$SCRIPT_DIR/get-session-key.sh")
+POINTERS_DIR="$PROJECT_DIR/.claude/bridge-sessions"
+POINTER_FILE="$POINTERS_DIR/$SESSION_KEY"
+
+# Reuse existing session if THIS agent session already has a valid one
+if [ -f "$POINTER_FILE" ]; then
+  EXISTING_ID=$(cat "$POINTER_FILE")
   EXISTING_DIR="$BRIDGE_DIR/sessions/$EXISTING_ID"
 
   if [ -d "$EXISTING_DIR" ] && [ -f "$EXISTING_DIR/manifest.json" ]; then
-    # Update heartbeat and reuse
+    # Update heartbeat (and label if a new one was given) and reuse
     NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
     TMP=$(mktemp "$EXISTING_DIR/manifest.XXXXXX")
-    jq --arg hb "$NOW" '.lastHeartbeat = $hb' "$EXISTING_DIR/manifest.json" > "$TMP"
+    if [ -n "$LABEL" ]; then
+      jq --arg hb "$NOW" --arg lb "$LABEL" '.lastHeartbeat = $hb | .label = $lb' "$EXISTING_DIR/manifest.json" > "$TMP"
+    else
+      jq --arg hb "$NOW" '.lastHeartbeat = $hb' "$EXISTING_DIR/manifest.json" > "$TMP"
+    fi
     mv "$TMP" "$EXISTING_DIR/manifest.json"
     echo -n "$EXISTING_ID"
     exit 0
   fi
 fi
 
+# Default label: current git branch (same-repo sessions are usually on different branches)
+if [ -z "$LABEL" ]; then
+  LABEL=$(git -C "$PROJECT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+fi
+
 # Create new session
 SESSION_ID=$(set +o pipefail; LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 6)
 
@@ -36,24 +65,30 @@ mkdir -p "$SESSION_DIR/inbox" "$SESSION_DIR/outbox"
 
 NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 MANIFEST_TMP=$(mktemp "$SESSION_DIR/manifest.XXXXXX")
-cat > "$MANIFEST_TMP" <<MANIFEST
-{
-  "sessionId": "$SESSION_ID",
-  "projectName": "$PROJECT_NAME",
-  "projectPath": "$PROJECT_DIR",
-  "startedAt": "$NOW",
-  "lastHeartbeat": "$NOW",
-  "status": "active",
-  "capabilities": ["query", "context-dump", "conversation"]
-}
-MANIFEST
+jq -n \
+  --arg sid "$SESSION_ID" \
+  --arg pname "$PROJECT_NAME" \
+  --arg ppath "$PROJECT_DIR" \
+  --arg label "$LABEL" \
+  --arg now "$NOW" \
+  '{
+    sessionId: $sid,
+    projectName: $pname,
+    projectPath: $ppath,
+    label: $label,
+    startedAt: $now,
+    lastHeartbeat: $now,
+    status: "active",
+    capabilities: ["query", "context-dump", "conversation"]
+  }' > "$MANIFEST_TMP"
 mv "$MANIFEST_TMP" "$SESSION_DIR/manifest.json"
 
-mkdir -p "$PROJECT_DIR/.claude"
-echo -n "$SESSION_ID" > "$BRIDGE_SESSION_FILE"
+mkdir -p "$POINTERS_DIR"
+echo -n "$SESSION_ID" > "$POINTER_FILE"
 
 if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
   echo "BRIDGE_SESSION_ID=$SESSION_ID" >> "$CLAUDE_ENV_FILE"
+  echo "BRIDGE_SESSION_KEY=$SESSION_KEY" >> "$CLAUDE_ENV_FILE"
 fi
 
 echo -n "$SESSION_ID"
diff --git a/plugins/session-bridge/scripts/send-message.sh b/plugins/session-bridge/scripts/send-message.sh
index b9ea135..2c410ff 100755
--- a/plugins/session-bridge/scripts/send-message.sh
+++ b/plugins/session-bridge/scripts/send-message.sh
@@ -25,11 +25,13 @@ fi
 MSG_ID="msg-$(set +o pipefail; LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 12)"
 NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
-# Read sender project name from manifest
+# Read sender project name and label from manifest
 SENDER_PROJECT="unknown"
+SENDER_LABEL=""
 SENDER_MANIFEST="$BRIDGE_DIR/sessions/$SENDER_ID/manifest.json"
 if [ -f "$SENDER_MANIFEST" ]; then
   SENDER_PROJECT=$(jq -r '.projectName // "unknown"' "$SENDER_MANIFEST")
+  SENDER_LABEL=$(jq -r '.label // ""' "$SENDER_MANIFEST")
 fi
 
 # Format inReplyTo as JSON (null or quoted string)
@@ -48,6 +50,7 @@ MSG_JSON=$(jq -n \
   --arg ts "$NOW" \
   --arg content "$CONTENT" \
   --arg fromProject "$SENDER_PROJECT" \
+  --arg fromLabel "$SENDER_LABEL" \
   --argjson inReplyTo "$IN_REPLY_TO_JSON" \
   '{
     id: $id,
@@ -60,7 +63,8 @@ MSG_JSON=$(jq -n \
     inReplyTo: $inReplyTo,
     metadata: {
       urgency: "normal",
-      fromProject: $fromProject
+      fromProject: $fromProject,
+      fromLabel: $fromLabel
     }
   }')
 
diff --git a/plugins/session-bridge/skills/bridge-awareness/SKILL.md b/plugins/session-bridge/skills/bridge-awareness/SKILL.md
index d69ffb4..fe05416 100644
--- a/plugins/session-bridge/skills/bridge-awareness/SKILL.md
+++ b/plugins/session-bridge/skills/bridge-awareness/SKILL.md
@@ -19,13 +19,16 @@ When the user asks you to communicate with a peer — whether via `/bridge ask`,
    ```
    Then find connected peers:
    ```bash
-   find ~/.claude/session-bridge/sessions/$MY_SESSION/inbox -name "*.json" -exec jq -r 'select(.type == "ping") | "\(.metadata.fromProject) (\(.from))"' {} \; 2>/dev/null | sort -u
+   find ~/.claude/session-bridge/sessions/$MY_SESSION/inbox -name "*.json" -exec jq -r 'select(.type == "ping") | "\(.metadata.fromProject) [\(.metadata.fromLabel // "")] (\(.from))"' {} \; 2>/dev/null | sort -u
    ```
+   `metadata.fromLabel` (git branch by default, or the peer's `--as` value) is available for disambiguation when several peers share a project name.
    If no connected peers found but the user specified a peer by name or session ID, connect first:
    ```bash
    BRIDGE_SESSION_ID=$MY_SESSION bash "${CLAUDE_PLUGIN_ROOT}/scripts/connect-peer.sh" "<peer-id>"
    ```
-2. If multiple peers, pick the most relevant one (by project name) or ask the user.
+2. If multiple peers, pick the most relevant one by label first (git branch by default, or the peer's `--as` role) — several sessions may share one project name — then by project name. Ask the user if still ambiguous.
+
+   Multiple agent sessions can run in the same repo; each registers independently and is distinguished by its label and session ID.
 3. Send the query and capture the message ID:
    ```bash
    MSG_ID=$(BRIDGE_SESSION_ID=$MY_SESSION bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <peer-id> query "Your question here")
@@ -103,7 +106,7 @@ BRIDGE_SESSION_ID=<TO_ID> bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-message.sh" <
 - **Outside listen mode, use `get-session-id.sh`** to get your session ID reliably.
 - **Never use `$(cat .claude/bridge-session)` directly** — it's a relative path that breaks when the working directory changes.
 - **Include real code in responses** — read actual files and paste relevant sections. Don't just describe changes in prose.
-- **Route to the right peer** when connected to multiple. Use project names to decide relevance.
+- **Route to the right peer** when connected to multiple. Use peer labels (git branch by default, or the `--as` role) to distinguish sessions — including multiple sessions in the same repo — then project name. Ask the user if still ambiguous.
 - **Act on responses.** When you get a response from a peer, don't just display it — use it to continue the user's task.
 - **Handle follow-up questions.** If a peer's response asks you a question back, answer it and re-query. Continue the back-and-forth until you get a final answer.
 - **Query proactively on upgrades.** Don't wait for compile errors — ask the peer immediately when the user mentions upgrading a dependency.
diff --git a/plugins/session-bridge/tests/test-cleanup.sh b/plugins/session-bridge/tests/test-cleanup.sh
index 25ba907..4377c76 100755
--- a/plugins/session-bridge/tests/test-cleanup.sh
+++ b/plugins/session-bridge/tests/test-cleanup.sh
@@ -10,6 +10,9 @@ REGISTER="$PLUGIN_DIR/scripts/register.sh"
 SEND_MSG="$PLUGIN_DIR/scripts/send-message.sh"
 CLEANUP="$PLUGIN_DIR/scripts/cleanup.sh"
 
+# Session key the scripts will compute for this process tree (BRIDGE_SESSION_KEY unset)
+KEY=$(bash "$PLUGIN_DIR/scripts/get-session-key.sh")
+
 TEST_TMPDIR=$(mktemp -d)
 trap 'rm -rf "$TEST_TMPDIR"' EXIT
 
@@ -42,13 +45,13 @@ else
   echo "  FAIL: session dir still exists"; FAIL=$((FAIL + 1))
 fi
 
-# --- Test 2: bridge-session pointer removed ---
+# --- Test 2: per-session pointer removed ---
 echo ""
-echo "Test 2: bridge-session file removed"
-if [ ! -f "$PROJECT_A/.claude/bridge-session" ]; then
-  echo "  PASS: bridge-session file removed"; PASS=$((PASS + 1))
+echo "Test 2: per-session pointer removed"
+if [ ! -f "$PROJECT_A/.claude/bridge-sessions/$KEY" ]; then
+  echo "  PASS: per-session pointer removed"; PASS=$((PASS + 1))
 else
-  echo "  FAIL: bridge-session file still exists"; FAIL=$((FAIL + 1))
+  echo "  FAIL: per-session pointer still exists"; FAIL=$((FAIL + 1))
 fi
 
 # --- Test 3: ALL peers notified with session-ended ---
@@ -100,16 +103,16 @@ else
   echo "  FAIL: stale session still exists"; FAIL=$((FAIL + 1))
 fi
 
-# --- Test 5: No-op when bridge-session file doesn't exist ---
+# --- Test 5: No-op when no session pointer exists ---
 echo ""
-echo "Test 5: Cleanup is no-op when no bridge-session file"
+echo "Test 5: Cleanup is no-op when no per-session pointer"
 PROJECT_E="$TEST_TMPDIR/project-e"
 mkdir -p "$PROJECT_E"
-# Don't register — no bridge-session file
+# Don't register — no pointer file
 if BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_E" bash "$CLEANUP" 2>/dev/null; then
-  echo "  PASS: cleanup exits cleanly with no bridge-session"; PASS=$((PASS + 1))
+  echo "  PASS: cleanup exits cleanly with no session pointer"; PASS=$((PASS + 1))
 else
-  echo "  FAIL: cleanup errored without bridge-session"; FAIL=$((FAIL + 1))
+  echo "  FAIL: cleanup errored without session pointer"; FAIL=$((FAIL + 1))
 fi
 
 # --- Test 6: Active sessions not cleaned by stale cleanup ---
diff --git a/plugins/session-bridge/tests/test-get-session-id.sh b/plugins/session-bridge/tests/test-get-session-id.sh
index 014484c..3051206 100755
--- a/plugins/session-bridge/tests/test-get-session-id.sh
+++ b/plugins/session-bridge/tests/test-get-session-id.sh
@@ -84,10 +84,28 @@ else
   echo "  FAIL: both returned same session"; FAIL=$((FAIL + 1))
 fi
 
-# --- Test 7: Prefers direct bridge-session file when in project root ---
+# --- Test 7: Prefers per-session pointer when in project root ---
 echo ""
-echo "Test 7: Fast path — uses bridge-session file directly when available"
+echo "Test 7: Fast path — uses per-session pointer directly when available"
 FOUND=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_DIR" bash "$GET_ID")
 assert_eq "fast path works" "$SESSION_ID" "$FOUND"
 
+# --- Test 8: Two sessions in the same repo resolve by session key ---
+echo ""
+echo "Test 8: Two sessions in same repo — each key resolves its own session"
+SHARED="$TEST_TMPDIR/shared-repo"
+mkdir -p "$SHARED/src"
+ID_A=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$SHARED" bash "$REGISTER")
+ID_B=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$SHARED" bash "$REGISTER")
+
+FOUND_KEY_A=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$SHARED" bash "$GET_ID")
+FOUND_KEY_B=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$SHARED" bash "$GET_ID")
+assert_eq "agent-a resolves from project root" "$ID_A" "$FOUND_KEY_A"
+assert_eq "agent-b resolves from project root" "$ID_B" "$FOUND_KEY_B"
+
+FOUND_KEY_A_SUB=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$SHARED/src" bash "$GET_ID")
+FOUND_KEY_B_SUB=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$SHARED/src" bash "$GET_ID")
+assert_eq "agent-a resolves from subdirectory" "$ID_A" "$FOUND_KEY_A_SUB"
+assert_eq "agent-b resolves from subdirectory" "$ID_B" "$FOUND_KEY_B_SUB"
+
 print_results
diff --git a/plugins/session-bridge/tests/test-heartbeat.sh b/plugins/session-bridge/tests/test-heartbeat.sh
index 2270f4d..702db5a 100755
--- a/plugins/session-bridge/tests/test-heartbeat.sh
+++ b/plugins/session-bridge/tests/test-heartbeat.sh
@@ -48,9 +48,9 @@ else
   echo "  FAIL: heartbeat not updated (still $OLD_HB)"; FAIL=$((FAIL + 1))
 fi
 
-# --- Test 2: Heartbeat via bridge-session file fallback ---
+# --- Test 2: Heartbeat via per-session pointer fallback ---
 echo ""
-echo "Test 2: Heartbeat via bridge-session file fallback updates lastHeartbeat"
+echo "Test 2: Heartbeat via per-session pointer fallback updates lastHeartbeat"
 
 # Set heartbeat to old value again
 OLD_HB="2020-01-01T00:00:00Z"
@@ -61,12 +61,12 @@ mv "$TMP" "$MANIFEST"
 CURRENT_HB=$(jq -r '.lastHeartbeat' "$MANIFEST")
 assert_eq "heartbeat set to old value again" "$OLD_HB" "$CURRENT_HB"
 
-# Run heartbeat without BRIDGE_SESSION_ID, relying on bridge-session file
+# Run heartbeat without BRIDGE_SESSION_ID, relying on the per-session pointer
 BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_A" bash "$HEARTBEAT"
 
 UPDATED_HB=$(jq -r '.lastHeartbeat' "$MANIFEST")
 if [ "$UPDATED_HB" != "$OLD_HB" ]; then
-  echo "  PASS: heartbeat updated via bridge-session file"; PASS=$((PASS + 1))
+  echo "  PASS: heartbeat updated via per-session pointer"; PASS=$((PASS + 1))
 else
   echo "  FAIL: heartbeat not updated via fallback (still $OLD_HB)"; FAIL=$((FAIL + 1))
 fi
diff --git a/plugins/session-bridge/tests/test-integration.sh b/plugins/session-bridge/tests/test-integration.sh
index f5dae86..a2b8007 100755
--- a/plugins/session-bridge/tests/test-integration.sh
+++ b/plugins/session-bridge/tests/test-integration.sh
@@ -14,6 +14,9 @@ RECEIVE="$PLUGIN_DIR/scripts/bridge-receive.sh"
 CLEANUP="$PLUGIN_DIR/scripts/cleanup.sh"
 LIST_PEERS="$PLUGIN_DIR/scripts/list-peers.sh"
 
+# Session key the scripts will compute for this process tree (BRIDGE_SESSION_KEY unset)
+KEY=$(bash "$PLUGIN_DIR/scripts/get-session-key.sh")
+
 TEST_TMPDIR=$(mktemp -d)
 trap 'rm -rf "$TEST_TMPDIR"' EXIT
 
@@ -104,7 +107,7 @@ echo "Scenario 4: Cleanup notifies peers and removes session"
 
 BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_A" bash "$CLEANUP"
 assert_eq "session A dir removed" "false" "$([ -d "$BRIDGE_DIR/sessions/$SESSION_A" ] && echo true || echo false)"
-assert_eq "bridge-session pointer removed" "false" "$([ -f "$PROJECT_A/.claude/bridge-session" ] && echo true || echo false)"
+assert_eq "per-session pointer removed" "false" "$([ -f "$PROJECT_A/.claude/bridge-sessions/$KEY" ] && echo true || echo false)"
 
 FOUND_ENDED=false
 for F in "$BRIDGE_DIR/sessions/$SESSION_B/inbox"/msg-*.json; do
@@ -133,7 +136,7 @@ echo "Scenario 6: Re-register after cleanup creates new session"
 NEW_SESSION=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_A" bash "$REGISTER")
 assert_eq "new session is different" "true" "$([ "$NEW_SESSION" != "$SESSION_A" ] && echo true || echo false)"
 assert_dir_exists "new session inbox exists" "$BRIDGE_DIR/sessions/$NEW_SESSION/inbox"
-assert_file_exists "new bridge-session file" "$PROJECT_A/.claude/bridge-session"
-assert_eq "bridge-session points to new ID" "$NEW_SESSION" "$(cat "$PROJECT_A/.claude/bridge-session")"
+assert_file_exists "new per-session pointer" "$PROJECT_A/.claude/bridge-sessions/$KEY"
+assert_eq "pointer points to new ID" "$NEW_SESSION" "$(cat "$PROJECT_A/.claude/bridge-sessions/$KEY")"
 
 print_results
diff --git a/plugins/session-bridge/tests/test-register.sh b/plugins/session-bridge/tests/test-register.sh
index 3f6a0da..9394951 100755
--- a/plugins/session-bridge/tests/test-register.sh
+++ b/plugins/session-bridge/tests/test-register.sh
@@ -8,6 +8,9 @@ source "$SCRIPT_DIR/test-helpers.sh"
 PLUGIN_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 REGISTER="$PLUGIN_DIR/scripts/register.sh"
 
+# Session key register.sh will compute for this process tree (BRIDGE_SESSION_KEY unset)
+KEY=$(bash "$PLUGIN_DIR/scripts/get-session-key.sh")
+
 TEST_TMPDIR=$(mktemp -d)
 trap 'rm -rf "$TEST_TMPDIR"' EXIT
 
@@ -19,13 +22,18 @@ echo "=== test-register.sh ==="
 
 # --- Test 1: Creates all expected files/dirs ---
 echo ""
-echo "Test 1: Creates manifest.json, inbox/, outbox/, bridge-session"
+echo "Test 1: Creates manifest.json, inbox/, outbox/, per-session pointer"
 SESSION_ID=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER")
 SESSION_DIR="$BRIDGE_DIR/sessions/$SESSION_ID"
 assert_file_exists "manifest.json exists" "$SESSION_DIR/manifest.json"
 assert_dir_exists "inbox/ exists" "$SESSION_DIR/inbox"
 assert_dir_exists "outbox/ exists" "$SESSION_DIR/outbox"
-assert_file_exists "bridge-session exists" "$PROJECT_DIR/.claude/bridge-session"
+assert_file_exists "per-session pointer exists" "$PROJECT_DIR/.claude/bridge-sessions/$KEY"
+if [ ! -f "$PROJECT_DIR/.claude/bridge-session" ]; then
+  echo "  PASS: legacy bridge-session pointer NOT created"; PASS=$((PASS + 1))
+else
+  echo "  FAIL: legacy bridge-session pointer exists"; FAIL=$((FAIL + 1))
+fi
 
 # --- Test 2: Manifest has correct fields ---
 echo ""
@@ -35,6 +43,7 @@ assert_eq "sessionId matches" "$SESSION_ID" "$(echo "$MANIFEST" | jq -r '.sessio
 assert_eq "projectPath matches" "$PROJECT_DIR" "$(echo "$MANIFEST" | jq -r '.projectPath')"
 assert_eq "status is active" "active" "$(echo "$MANIFEST" | jq -r '.status')"
 assert_eq "projectName is dir basename" "my-project" "$(echo "$MANIFEST" | jq -r '.projectName')"
+assert_eq "label field exists (empty in non-git dir)" "" "$(echo "$MANIFEST" | jq -r '.label')"
 if [ -n "$(echo "$MANIFEST" | jq -r '.startedAt')" ]; then
   echo "  PASS: startedAt is set"; PASS=$((PASS + 1))
 else
@@ -46,10 +55,15 @@ else
   echo "  FAIL: lastHeartbeat is missing"; FAIL=$((FAIL + 1))
 fi
 
-# --- Test 3: bridge-session pointer is correct ---
+# --- Test 3: per-session pointer is correct ---
 echo ""
-echo "Test 3: bridge-session file contains session ID"
-assert_eq "bridge-session contains session ID" "$SESSION_ID" "$(cat "$PROJECT_DIR/.claude/bridge-session")"
+echo "Test 3: per-session pointer file contains session ID"
+assert_eq "bridge-sessions/$KEY contains session ID" "$SESSION_ID" "$(cat "$PROJECT_DIR/.claude/bridge-sessions/$KEY")"
+if [ ! -f "$PROJECT_DIR/.claude/bridge-session" ]; then
+  echo "  PASS: legacy bridge-session pointer still absent"; PASS=$((PASS + 1))
+else
+  echo "  FAIL: legacy bridge-session pointer exists"; FAIL=$((FAIL + 1))
+fi
 
 # --- Test 4: Session ID format ---
 echo ""
@@ -70,6 +84,7 @@ PROJECT_DIR2="$TEST_TMPDIR/my-project-2"
 mkdir -p "$PROJECT_DIR2"
 SESSION_ID2=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_DIR2" CLAUDE_ENV_FILE="$ENV_FILE" bash "$REGISTER")
 assert_contains "BRIDGE_SESSION_ID in env file" "BRIDGE_SESSION_ID=$SESSION_ID2" "$(cat "$ENV_FILE")"
+assert_contains "BRIDGE_SESSION_KEY in env file" "BRIDGE_SESSION_KEY=$KEY" "$(cat "$ENV_FILE")"
 
 # --- Test 6: Re-registering same project reuses session ---
 echo ""
@@ -79,7 +94,7 @@ assert_eq "reused same session ID" "$SESSION_ID" "$SESSION_ID_AGAIN"
 
 # --- Test 7: Stale pointer (session dir missing) creates new session ---
 echo ""
-echo "Test 7: Stale bridge-session pointer — creates new session when dir is gone"
+echo "Test 7: Stale per-session pointer — creates new session when dir is gone"
 # Manually delete the session dir to simulate a stale pointer
 rm -rf "$SESSION_DIR"
 NEW_SESSION_ID=$(BRIDGE_DIR="$BRIDGE_DIR" PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER")
@@ -121,4 +136,28 @@ else
   echo "  FAIL: heartbeat not updated"; FAIL=$((FAIL + 1))
 fi
 
+# --- Test 10: Same project, different session keys → distinct sessions ---
+echo ""
+echo "Test 10: Same project, different session keys get different session IDs"
+ID_K1=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=key-1 PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER")
+ID_K2=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=key-2 PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER")
+if [ "$ID_K1" != "$ID_K2" ]; then
+  echo "  PASS: different keys get different session IDs"; PASS=$((PASS + 1))
+else
+  echo "  FAIL: same session ID for different keys"; FAIL=$((FAIL + 1))
+fi
+assert_dir_exists "key-1 session dir exists" "$BRIDGE_DIR/sessions/$ID_K1"
+assert_dir_exists "key-2 session dir exists" "$BRIDGE_DIR/sessions/$ID_K2"
+assert_file_exists "key-1 pointer exists" "$PROJECT_DIR/.claude/bridge-sessions/key-1"
+assert_file_exists "key-2 pointer exists" "$PROJECT_DIR/.claude/bridge-sessions/key-2"
+
+# --- Test 11: --as sets label; re-register with --as updates label ---
+echo ""
+echo "Test 11: --as label set on register, updated on re-register"
+ID_L1=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=label-key PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER" --as backend)
+assert_eq "label is backend" "backend" "$(jq -r '.label' "$BRIDGE_DIR/sessions/$ID_L1/manifest.json")"
+ID_L2=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=label-key PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER" --as frontend)
+assert_eq "re-register reuses session" "$ID_L1" "$ID_L2"
+assert_eq "label updated to frontend" "frontend" "$(jq -r '.label' "$BRIDGE_DIR/sessions/$ID_L1/manifest.json")"
+
 print_results
diff --git a/plugins/session-bridge/tests/test-same-repo.sh b/plugins/session-bridge/tests/test-same-repo.sh
new file mode 100644
index 0000000..fc49257
--- /dev/null
+++ b/plugins/session-bridge/tests/test-same-repo.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# tests/test-same-repo.sh — Two agent sessions in the SAME project dir as distinct peers
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+PLUGIN_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REGISTER="$PLUGIN_DIR/scripts/register.sh"
+GET_ID="$PLUGIN_DIR/scripts/get-session-id.sh"
+SEND_MSG="$PLUGIN_DIR/scripts/send-message.sh"
+CONNECT="$PLUGIN_DIR/scripts/connect-peer.sh"
+LISTEN="$PLUGIN_DIR/scripts/bridge-listen.sh"
+RECEIVE="$PLUGIN_DIR/scripts/bridge-receive.sh"
+CLEANUP="$PLUGIN_DIR/scripts/cleanup.sh"
+LIST_PEERS="$PLUGIN_DIR/scripts/list-peers.sh"
+
+TEST_TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+BRIDGE_DIR="$TEST_TMPDIR/bridge"
+PROJECT_DIR="$TEST_TMPDIR/my-project"
+mkdir -p "$PROJECT_DIR"
+
+echo "=== test-same-repo.sh ==="
+
+# --- Scenario 1: Two agent sessions register in the same project as distinct peers ---
+echo ""
+echo "Scenario 1: Register backend and frontend in the same project dir"
+
+SESSION_A=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER" --as backend)
+SESSION_B=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER" --as frontend)
+echo "  Session A (backend): $SESSION_A  Session B (frontend): $SESSION_B"
+
+assert_eq "sessions are different" "true" "$([ "$SESSION_A" != "$SESSION_B" ] && echo true || echo false)"
+assert_file_exists "A manifest exists" "$BRIDGE_DIR/sessions/$SESSION_A/manifest.json"
+assert_file_exists "B manifest exists" "$BRIDGE_DIR/sessions/$SESSION_B/manifest.json"
+assert_eq "A label is backend" "backend" "$(jq -r '.label' "$BRIDGE_DIR/sessions/$SESSION_A/manifest.json")"
+assert_eq "B label is frontend" "frontend" "$(jq -r '.label' "$BRIDGE_DIR/sessions/$SESSION_B/manifest.json")"
+assert_file_exists "A pointer exists" "$PROJECT_DIR/.claude/bridge-sessions/agent-a"
+assert_file_exists "B pointer exists" "$PROJECT_DIR/.claude/bridge-sessions/agent-b"
+if [ ! -f "$PROJECT_DIR/.claude/bridge-session" ]; then
+  echo "  PASS: legacy bridge-session pointer absent"; PASS=$((PASS + 1))
+else
+  echo "  FAIL: legacy bridge-session pointer exists"; FAIL=$((FAIL + 1))
+fi
+
+# --- Scenario 2: get-session-id resolves each agent's own session ---
+echo ""
+echo "Scenario 2: get-session-id.sh resolves per session key (root and subdirectory)"
+
+FOUND_A=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$PROJECT_DIR" bash "$GET_ID")
+FOUND_B=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$PROJECT_DIR" bash "$GET_ID")
+assert_eq "agent-a resolves to session A" "$SESSION_A" "$FOUND_A"
+assert_eq "agent-b resolves to session B" "$SESSION_B" "$FOUND_B"
+
+SUBDIR="$PROJECT_DIR/src/ui"
+mkdir -p "$SUBDIR"
+FOUND_A_SUB=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$SUBDIR" bash "$GET_ID")
+FOUND_B_SUB=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$SUBDIR" bash "$GET_ID")
+assert_eq "agent-a resolves from subdirectory" "$SESSION_A" "$FOUND_A_SUB"
+assert_eq "agent-b resolves from subdirectory" "$SESSION_B" "$FOUND_B_SUB"
+
+# --- Scenario 3: Round trip between the two same-repo peers ---
+echo ""
+echo "Scenario 3: Connect, query, and respond between same-repo peers"
+
+BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_ID="$SESSION_A" bash "$CONNECT" "$SESSION_B" > /dev/null
+OUTPUT=$(BRIDGE_DIR="$BRIDGE_DIR" bash "$LISTEN" "$SESSION_B" 5)
+assert_contains "B sees ping from A" "TYPE=ping" "$OUTPUT"
+assert_contains "B sees sender label on ping" "FROM_LABEL=backend" "$OUTPUT"
+
+MSG_ID=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_ID="$SESSION_A" bash "$SEND_MSG" "$SESSION_B" query "What is the API base URL?")
+OUTPUT=$(BRIDGE_DIR="$BRIDGE_DIR" bash "$LISTEN" "$SESSION_B" 5)
+assert_contains "B sees query from A" "What is the API base URL?" "$OUTPUT"
+assert_contains "B knows sender is A" "FROM_ID=$SESSION_A" "$OUTPUT"
+assert_contains "B sees sender label on query" "FROM_LABEL=backend" "$OUTPUT"
+
+BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_ID="$SESSION_B" bash "$SEND_MSG" "$SESSION_A" response "Base URL is /api/v2" "$MSG_ID" > /dev/null
+OUTPUT=$(BRIDGE_DIR="$BRIDGE_DIR" bash "$RECEIVE" "$SESSION_A" "$MSG_ID" 10)
+assert_contains "A receives B's response" "Base URL is /api/v2" "$OUTPUT"
+assert_contains "response shows sender label" 'Response from my-project \[frontend\]:' "$OUTPUT"
+
+# --- Scenario 4: list-peers shows both labels ---
+echo ""
+echo "Scenario 4: list-peers shows both same-repo labels"
+OUTPUT=$(BRIDGE_DIR="$BRIDGE_DIR" bash "$LIST_PEERS")
+assert_contains "lists session A ID" "$SESSION_A" "$OUTPUT"
+assert_contains "lists session B ID" "$SESSION_B" "$OUTPUT"
+assert_contains "lists backend label" "backend" "$OUTPUT"
+assert_contains "lists frontend label" "frontend" "$OUTPUT"
+
+# --- Scenario 5: Cleanup of A removes only A and notifies B ---
+echo ""
+echo "Scenario 5: Cleanup of session A leaves session B intact"
+
+BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$PROJECT_DIR" bash "$CLEANUP"
+assert_eq "A session dir removed" "false" "$([ -d "$BRIDGE_DIR/sessions/$SESSION_A" ] && echo true || echo false)"
+assert_eq "A pointer removed" "false" "$([ -f "$PROJECT_DIR/.claude/bridge-sessions/agent-a" ] && echo true || echo false)"
+assert_dir_exists "B session dir still present" "$BRIDGE_DIR/sessions/$SESSION_B"
+assert_file_exists "B manifest intact" "$BRIDGE_DIR/sessions/$SESSION_B/manifest.json"
+assert_dir_exists "B inbox intact" "$BRIDGE_DIR/sessions/$SESSION_B/inbox"
+assert_file_exists "B pointer still present" "$PROJECT_DIR/.claude/bridge-sessions/agent-b"
+assert_eq "agent-b still resolves to B" "$SESSION_B" "$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$PROJECT_DIR" bash "$GET_ID")"
+
+FOUND_ENDED=false
+for F in "$BRIDGE_DIR/sessions/$SESSION_B/inbox"/msg-*.json; do
+  [ -f "$F" ] || continue
+  if [ "$(jq -r '.type' "$F")" = "session-ended" ] && [ "$(jq -r '.from' "$F")" = "$SESSION_A" ]; then
+    FOUND_ENDED=true
+    break
+  fi
+done
+if $FOUND_ENDED; then
+  echo "  PASS: B notified of A's departure via session-ended"; PASS=$((PASS + 1))
+else
+  echo "  FAIL: B not notified of A's departure"; FAIL=$((FAIL + 1))
+fi
+
+# --- Scenario 6: Re-registering agent-a creates a NEW session, B unaffected ---
+echo ""
+echo "Scenario 6: Re-register agent-a after cleanup"
+
+NEW_SESSION_A=$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-a PROJECT_DIR="$PROJECT_DIR" bash "$REGISTER" --as backend)
+assert_eq "new session ID differs from old" "true" "$([ "$NEW_SESSION_A" != "$SESSION_A" ] && echo true || echo false)"
+assert_dir_exists "new session inbox exists" "$BRIDGE_DIR/sessions/$NEW_SESSION_A/inbox"
+assert_eq "new pointer points to new ID" "$NEW_SESSION_A" "$(cat "$PROJECT_DIR/.claude/bridge-sessions/agent-a")"
+assert_eq "B still resolves to same session" "$SESSION_B" "$(BRIDGE_DIR="$BRIDGE_DIR" BRIDGE_SESSION_KEY=agent-b PROJECT_DIR="$PROJECT_DIR" bash "$GET_ID")"
+
+print_results