Enhance session management in team.sh and update documentation

- Updated `bin/init.sh` to append `.agents/.claude-session-id.*` to `.gitignore`, ensuring local session IDs are not committed.
- Revised `docs/TEAM.md` to clarify the behavior of session resumption, emphasizing the use of pinned UUIDs for each tmux session.
- Modified `templates/scripts/team.sh.tmpl` to implement UUID generation for session IDs, improving the management of Claude conversations across tmux sessions.

These changes aim to enhance user experience by ensuring that each tmux session maintains its own conversation context, preventing ambiguity in session management.

Author: MShokry

bin/init.sh

@@ -392,10 +392,12 @@ if [ "$FRESH_SCAFFOLD" -eq 1 ] && [ ! -f "$STAMP" ]; then
   printf 'init.sh: wrote %s\n' "$STAMP"
 fi
 
-# .agents/.oc-port is local machine state (which port scripts/team.sh last
-# bound), never something to commit. Append-if-missing when the target is a
-# git repo — additive only, in keeping with this script's never-overwrite
-# stance; a project that ignores it differently is left alone.
+# .agents/.oc-port and .agents/.claude-session-id.* are local machine state
+# (which port scripts/team.sh last bound; which Claude conversation each
+# tmux session name is pinned to), never something to commit.
+# Append-if-missing when the target is a git repo — additive only, in
+# keeping with this script's never-overwrite stance; a project that ignores
+# these differently is left alone.
 if [ -d "$TARGET/.git" ]; then
   GITIGNORE="$TARGET/.gitignore"
   if ! grep -qxF '.agents/.oc-port' "$GITIGNORE" 2>/dev/null; then
@@ -405,6 +407,13 @@ if [ -d "$TARGET/.git" ]; then
     } >> "$GITIGNORE"
     printf 'init.sh: added .agents/.oc-port to %s\n' "$GITIGNORE"
   fi
+  if ! grep -qxF '.agents/.claude-session-id.*' "$GITIGNORE" 2>/dev/null; then
+    {
+      printf '\n# local Claude session ids pinned per tmux session name by scripts/team.sh\n'
+      printf '.agents/.claude-session-id.*\n'
+    } >> "$GITIGNORE"
+    printf 'init.sh: added .agents/.claude-session-id.* to %s\n' "$GITIGNORE"
+  fi
 fi
 
 cat <<MSG

docs/TEAM.md

@@ -18,15 +18,26 @@ Flags can combine with a session name in any order:
 
 ## Resuming is the default
 
-Pane 0 runs `claude --continue`, which picks up the most recent
-conversation in this project's directory — not a fresh one. This exists
-because killing the tmux session (the usual way to free up a port, or just
-closing the terminal) used to also throw away the lead's context, with no
-way back into the same conversation. Now: kill it, come back later, run
-`scripts/team.sh` again, the lead is where you left it.
+Pane 0 resumes the lead's own conversation — not a fresh one — but it does
+so by pinning to a stored UUID (`.agents/.claude-session-id.<session-name>`,
+written the first time that session name runs) rather than
+`claude --continue`. `--continue` only means "the most recent conversation
+in this directory," with no notion of *which* tmux session started it, so
+running a second `scripts/team.sh` session name against the same repo (or
+just running a one-off `claude` there for something unrelated) could make
+the next `--continue` resume the wrong thread entirely. The pinned id
+removes that ambiguity: each session name always resumes its own
+conversation via `claude --resume <uuid>`, however many other Claude
+conversations have happened in the same directory since.
+
+This exists because killing the tmux session (the usual way to free up a
+port, or just closing the terminal) used to also throw away the lead's
+context, with no way back into the same conversation. Now: kill it, come
+back later, run `scripts/team.sh` again, the lead is where you left it.
 
 Pass `--fresh` on the rare run where you actually want a clean slate
-instead.
+instead — this mints a new pinned id, so later resumes follow the new
+conversation, not the old one.
 
 ## Running two projects at once
 

templates/scripts/team.sh.tmpl

@@ -15,15 +15,20 @@
 #   scripts/team.sh --port <N>             opencode server port (default 4096)
 #   scripts/team.sh --kill [session-name]
 #
-# Resuming is the default, not an opt-in: pane 0 runs `claude --continue`,
-# which picks up the most recent conversation in this project's directory.
-# That matters because killing this tmux session (the usual way to free up
-# a port so a second project can use scripts/team.sh at the same time) used
-# to also throw away the lead's context — there was no way back into the
-# same conversation short of scrolling terminal history. `--continue` fixes
-# that: kill the session, come back later, run scripts/team.sh again, the
-# lead picks up where it left off. Pass --fresh on the rare run where you
-# actually want a clean slate.
+# Resuming is the default, not an opt-in: pane 0 resumes the lead's own
+# Claude conversation, pinned to this session name via a stored UUID (see
+# .agents/.claude-session-id.<session-name>) rather than `claude --continue`
+# (which just means "the most recent conversation in this directory" — with
+# no notion of *which* tmux session started it, so a second team.sh session
+# name in the same repo, or even a one-off `claude` run there, could steal
+# the next --continue). That matters because killing this tmux session (the
+# usual way to free up a port so a second project can use scripts/team.sh at
+# the same time) used to also throw away the lead's context — there was no
+# way back into the same conversation short of scrolling terminal history.
+# The pinned session id fixes that: kill the session, come back later, run
+# scripts/team.sh again, the lead picks up its own thread — never someone
+# else's. Pass --fresh on the rare run where you actually want a clean
+# slate (this also mints a new pinned id, so future resumes follow it).
 #
 # Running two projects at once: opencode's server binds one port per
 # process, so two projects both defaulting to --port 4096 collide — the
@@ -66,6 +71,19 @@ fi
 
 command -v tmux >/dev/null 2>&1 || { echo "team.sh: tmux not found" >&2; exit 1; }
 
+gen_uuid() {
+  if command -v uuidgen >/dev/null 2>&1; then
+    uuidgen | tr '[:upper:]' '[:lower:]'
+  elif [ -r /proc/sys/kernel/random/uuid ]; then
+    cat /proc/sys/kernel/random/uuid
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import uuid; print(uuid.uuid4())'
+  else
+    echo "team.sh: need uuidgen or python3 to mint a Claude session id" >&2
+    exit 1
+  fi
+}
+
 if tmux has-session -t "$SESSION" 2>/dev/null; then
   echo "team.sh: session '$SESSION' already exists — attaching"
   exec tmux attach -t "$SESSION"
@@ -74,8 +92,21 @@ fi
 mkdir -p "$REPO_ROOT/.agents"
 printf '%s' "$PORT" > "$REPO_ROOT/.agents/.oc-port"
 
-CLAUDE_CMD="claude --continue"
-[ "$FRESH" -eq 1 ] && CLAUDE_CMD="claude"
+# Pin pane 0 to one Claude conversation per tmux session name (see usage
+# comment above for why --continue alone isn't enough).
+SESSION_ID_FILE="$REPO_ROOT/.agents/.claude-session-id.$SESSION"
+[ "$FRESH" -eq 1 ] && rm -f "$SESSION_ID_FILE"
+
+if [ -f "$SESSION_ID_FILE" ]; then
+  CLAUDE_UUID="$(cat "$SESSION_ID_FILE")"
+  # Fall back to re-minting under the same id if the stored conversation is
+  # gone (history pruned, project path changed) so the pane never just dies.
+  CLAUDE_CMD="claude --resume $CLAUDE_UUID || claude --session-id $CLAUDE_UUID"
+else
+  CLAUDE_UUID="$(gen_uuid)"
+  printf '%s' "$CLAUDE_UUID" > "$SESSION_ID_FILE"
+  CLAUDE_CMD="claude --session-id $CLAUDE_UUID"
+fi
 
 tmux new-session -d -s "$SESSION" -c "$REPO_ROOT" -n team