dylanroscover / multi-session-etiquette

<!-- Generated by Embody/Envoy - Do not remove this comment - sha:2217d5117c2491f7 -->

Multi-Session Etiquette

Multiple AI sessions (several client windows, different 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 TDXN 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.