multi-session-etiquette

name	multi-session-etiquette
description	MUST READ when a _peers advisory appears or multiple AI sessions are active in the same TouchDesigner project: advisory contract, claim leases, destructive gates, raw-file-edit visibility, division of labor.

Multi-Session Etiquette

Multiple AI sessions (Claude Code windows, other MCP clients) often work on the same TouchDesigner project at once -- same live network, same externalized files, same git tree. Envoy coordinates them; this rule is how you cooperate.

At session start

Call get_sessions once early. It lists every connected session (label, idle time, recent_scopes it modified, claims it holds, you = your own session id). If peers are active, prefer working in a subtree none of them touched recently.

Read the advisories -- they come to you

• Any tool response may carry _peers: another session touched territory overlapping your request (op path or externalized file) within ~10 min.
• conflict: false -- informational. Note it, re-read files before editing them, and avoid building on top of a peer's in-flight work.
• conflict: true (a peer WROTE there within the last minute) is a HARD STOP. Do not keep mutating that scope. Check get_sessions, tell the user who is working there, and either divide the work (different subtrees) or get explicit user direction before proceeding.
• A CONFLICT WARNING or MULTI-SESSION GATE line in _logs follows the same contract as a LAYOUT WARNING: never end a turn without addressing it.

Claim before big or destructive work

• Before a large build, a refactor of a COMP subtree, or editing an externalized file, call claim_scope with the NARROWEST scope that covers the work and a short note ("rebuilding camera rig"): an op-path prefix (/project1/scene), a file (file:scripts/tools.py), or a special scope (project:tests before a test run).
• Your own tool calls touching the scope renew the lease automatically; it expires on its TTL or when your session goes silent. release_scope when done is polite but never required for others to make progress.
• If a claim is refused, the response names the holder, their note, and the expiry. Coordinate or work elsewhere -- do NOT retry in a loop.

The task ledger -- state, not just presence

Claims say who is touching what right now; the ledger (.embody/tasks.json, via announce_task / update_task) says what state the WORK is in. It exists because a dirty tree plus recency signals cannot distinguish in-flight work from FINISHED work awaiting a commit -- and misreading that costs real coordination time.

• Starting substantive work (a feature, fix, refactor -- not single-tool edits): announce_task with a short title and the scopes it will touch. Worktree tasks announce IN ADDITION to their durable worktree claim.
• Finishing: flip to done_uncommitted the moment the work is complete but sitting uncommitted in the tree. This is the load-bearing state -- it is what stops a peer from reading your finished feature as in-flight work, and preflight_landing reports ledger tasks overlapping a landing.
• Committing: update_task(task_id, commit='<sha>') -- a sha alone implies the committed transition.
• Reading: get_sessions carries every session's active entries; check them at session start and before working in files another task names.
• Hygiene: any session may mark a dead session's stale task abandoned (the ledger records updated_by for non-owner writes).

Destructive operations are gated

• delete_op, import_network with clear_first=True, run_tests, and batches containing them are REFUSED while a live peer holds a claim on the scope or wrote it within the last minute.
• override=True exists for when you are CERTAIN -- e.g. the "peer" is the same user's stale session, or the user explicitly told you to proceed. Never override silently: state in your reply that you overrode and why.

Raw file edits are invisible to Envoy

• Envoy only sees MCP traffic. Editing an externalized file with your own file tools (Edit/Write) leaves no touch record -- so before editing one, check get_sessions (does a peer claim it or list it in recent_scopes?) and claim it yourself (file:<repo-relative-path>) for the duration.
• Re-read a file before editing whenever a peer's recent_scopes mentions it: your cached copy may be stale.

Worktrees are scoped territory too

Isolated-worktree work (../<repo>-wt-<task>, see rules/worktree-td-safety.md) is doubly invisible: the edits are raw file edits AND they happen outside the repo Envoy watches. Peers cannot see any of it until the diff lands. So coordinate by intent, not by touch records:

• On starting a worktree task: claim project:worktree-<task> (e.g. project:worktree-watchdog) with a note naming the files/subsystem the diff will land on. This is how peers learn a worktree task is in flight. Worktree claims are DURABLE -- they survive session death and Envoy restarts, expiring only when the worktree directory is removed (7-day backstop); get_sessions lists them under worktrees.
• Before landing the diff: claim file:<repo-relative-path> for each externalized file the diff touches (or the narrowest shared parent scope). If a peer holds one, reconcile first -- landing over a peer's in-flight edit is the worktree version of a blind overwrite. Run preflight_landing(worktree_path) FIRST -- it intersects the landing's files with main-tree dirt, peer file territory, and unsaved live TDN state in one call; a conflicts verdict means reconcile before any file moves.
• Two sessions must never share one worktree -- one writer per checkout, always. A second session starts its own ../<repo>-wt-<other-task>.
• Access is pre-authorized: Envoy's generated settings allow Read/Edit in sibling <repo>-wt-* folders, so worktree work never needs permission prompts (keep the -wt- naming for this to apply).

Division of labor

The cheapest coordination is spatial: agree (via the user) on separate COMP subtrees or file areas per session. Claims make that agreement visible and enforceable.