termcanvas-agent-sync-debugging

Debug TermCanvas restore, agent sync, and rendering stability

Use this workflow to identify whether the failing layer is persisted agent identity, restore ordering, renderer polling, terminal geometry, xterm rendering, or PTY/tmux I/O before changing lifecycle code.

Failure pattern: A release relaunch creates and saves duplicate terminal views, sometimes on the wrong canvas, when agent sync races partial session hydration. Related paths include folderless projects being skipped and periodic renderer work changing geometry or exhausting WebGL contexts.

Verified by: Normalizing a real polluted release snapshot reduced 20 nodes to 15 unique nodes; an isolated Electron relaunch restored all 15 with duplicateIdentities: []. npm run build passed and all 249 tests passed. Prior checks also reproduced the folderless sync mismatch, improved scoped polling from about 0.55s to 0.20s, held 10-terminal WebGL use to 8, and preserved tail mount height 486.4609375 and terminal size 116x27. The deleted-session path was verified by restoring two exact OpenCode session IDs, rebuilding their parent chain, and observing both running tmux sessions materialize in TermCanvas.

Procedure

1. Diagnose release-relaunch duplicates from the saved session

• Quit or isolate the release app before drawing conclusions from changing state. Inspect its persisted session first:

  jq '
    [.canvases[] as $canvas | $canvas.terminalNodes[]? | {
      canvasId: $canvas.id,
      canvasProjectTag: $canvas.agentProjectTag,
      sessionKey,
      tmuxSessionName,
      managedProjectTag,
      managedAgentName
    }] as $nodes
    | {
        bySessionKey: ($nodes | group_by(.sessionKey)
          | map(select(.[0].sessionKey != null and length > 1))),
        byTmuxSession: ($nodes | group_by(.tmuxSessionName)
          | map(select(.[0].tmuxSessionName != null and length > 1))),
        byProjectAgent: ($nodes | group_by([.managedProjectTag,.managedAgentName])
          | map(select(.[0].managedProjectTag != null
            and .[0].managedAgentName != null and length > 1)))
      }
  ' "$HOME/Library/Application Support/TermCanvas/app-session.json"