avatar-regression-probes

name	avatar-regression-probes
description	Validate Squad avatar regressions with alias-resolution probes and source assertions around reset paths.
domain	testing, extension-ui
confidence	high
source	earned

Context

Use this when CopilotAvatar changes touch Squad identity, sub-agent badges, or session-to-session replay behavior. The repo has no built-in test suite for the extension, so reliable review work needs a compact probe that exercises both the data seam and the UI-state seam.

Patterns

• Run node --check on .github/extensions/copilot-avatar/main.mjs, .github/extensions/copilot-avatar/lib/squad-context.mjs, and .github/extensions/copilot-avatar/content/main.js before trusting anything else.
• Probe loadSquadContext() from the repo root and from a clearly non-Squad cwd to verify both the positive and negative paths.
• Use resolveSquadAgentMetadata() against casting aliases like lead, backend-dev, and tester so roster-name regressions show up immediately.
• Add targeted source assertions for stale-state boundaries: reset every runtime cache in main.mjs, clear non-root avatars in content/main.js, and keep the reset wired to session start, context change, and scope drift.
• Add a prompt-boundary assertion: assistant.turn_start must clear sub-agent runtime state before any Squad-context refresh or replay hook runs, or prior-turn Copilot-presence/tool state can resurrect a whole graveyard of cards for one ugly flash.
• Add targeted source assertions for no-terminal-event leaks: if a visible sub-agent finishes its last tool without a matching subagent.completed / subagent.failed, the extension still needs a fallback retire path instead of leaving an idle ghost on screen until the next directive.
• Add a late-open stale-card assertion: before replaying session.getMessages() back into an open webview, clear non-root avatars and reset backend sub-agent caches so idle background agents from older turns cannot survive as fake live cards.
• For stale-idle ghost checks, live-probe the page by queueing setAgentIntent / setAgentActivity / setAgentThinking for a missing non-root agentId, rendering a generic stale card, calling clearSubagents({ preserveRoot: true }), then re-adding that same agentId with a real name. The card must come back Idle with empty detail, proving both visible ghosts and pending UI caches were actually wiped.
• Add targeted source assertions for the live-signal paths: placeholder labels should yield to Squad names, per-subagent model hooks should still flow through assistant.usage / tool.execution_complete / session.model_change, and getAvatarBadgeText() should still prefer current activity text.
• Add a root-overlay suppression assertion: if Squad idle chrome should be silent, clear statusText / detailText in the runtime payload and make the webview honor explicit empty strings instead of reviving fallback copy like Squad ready.
• Add a visibility-ownership assertion: subagent.started should be enough to drive addSubagent for a Copilot-owned runtime agent, with no extra first-render debounce or tool-evidence gate layered on top.
• Add a wrapper-tool assertion for the root agent: parent spawn tools such as task, agent, and runSubagent should not mirror into the root badge/subtask overlay unless the product explicitly wants that orchestration text visible.
• Add a duplicate-identity probe: two different runtime agentId values that both resolve to the same cast identity (for example Tony Stark) must not remain visible together unless the product explicitly wants parallel clones.
• Add targeted source assertions for Squad-only root visuals: root accessories should be created only for ROOT_AGENT_ID, then toggled from window.setSquadContext(payload.active) instead of any separate cwd sniff inside the webview.
• If an extension pushes state immediately after webview.show(), add a page-owned readiness latch (for example window.__copilotAvatarReady) and wait for it before sending root-only state like setSquadContext(). A live handle or websocket alone does not prove the page module has finished defining its API.
• If a root-only Squad signal can arrive before the root avatar exists, latch it in page state and replay it during initializeRootAvatar() / root-avatar creation so the first visible frame picks up the correct chrome.
• For late-open badge regressions, queue setAgentThinking / setAgentIntent / setAgentActivity against a missing non-root agentId, assert no .subagent-label[data-agent-id="..."] exists yet, then send addSubagent with the resolved Squad payload and verify the card appears with the cast name, visible thinking/running badge state, and the assigned work description in .agent-detail.
• After a real read-only probe, poll the live avatar window and count visible cards by display name. Static regex/source assertions can all pass while duplicate cast cards or blank idle ghosts still survive in the rendered UI.
• To prove two named agents are visible together, overlap a long-running read-only lead/root probe with a second read-only sub-agent probe, then snapshot the live .subagent-label cards immediately during that overlap window.
• If the user explicitly wants to see specific cast identities and the live runtime does not surface them, stage a transient webview-only demo with clearSubagents({ preserveRoot: true }), addSubagent, setAgentIntent, and setAgentActivity after the real probe. Use it to make Tony/Howard/etc. visibly inspectable, but never mistake that demo for evidence that the runtime event pipeline is healthy.
• Before blaming the webview, check which copilot-avatar extension process is actually running and reload extensions after local .github/extensions/copilot-avatar/*.mjs edits. A live avatar window can keep stale extension behavior even when the on-disk source already contains the identity fix.
• When refining Squad-only root flair, keep the silhouette minimal: reuse the same root lifecycle hooks, with a face-side curved mic boom + compact capsule. Preferred finish is dark graphite (0x1c1c1c). Extend the boom curve from the temple/ear region down to the mouth with 5–6 CatmullRom points for a natural arc without an ear-ring anchor.

Examples

• .github/extensions/copilot-avatar/lib/squad-context.mjs should resolve tester → Howard the Duck, backend-dev → Peter Parker, lead → Tony Stark.
• .github/extensions/copilot-avatar/main.mjs should call resetSubagentRuntimeState({ clearUi: true }) before rehydrating later views.
• .github/extensions/copilot-avatar/main.mjs should clear non-root cards, reset sub-agent caches, and then hydrate from session.getMessages() when a late-open/reload path rebuilds the avatar window.
• .github/extensions/copilot-avatar/main.mjs should run resetSubagentRuntimeState({ clearUi: true }) inside assistant.turn_start before refreshVisibleSquadContext() / syncKnownSubagents() can replay anything.
• .github/extensions/copilot-avatar/main.mjs should call ensureSubagentVisible() from subagent.started instead of waiting for tool.execution_start / tool.execution_progress to unlock first render.
• .github/extensions/copilot-avatar/lib/squad-context.mjs can keep getSquadWindowContext() active while sending blank statusText / detailText, and .github/extensions/copilot-avatar/content/main.js should preserve those blanks instead of falling back to Squad ready.
• .github/extensions/copilot-avatar/content/main.js should expose clearSubagents({ preserveRoot: true }) so stale Squad cards disappear when Squad turns off.
• .github/extensions/copilot-avatar/main.mjs can gate root-level setAgentActivity / setSubtask calls behind a helper like shouldMirrorRootToolActivity() so wrapper tools do not flash task on the root overlay.
• .github/extensions/copilot-avatar/main.mjs should not rely on tool.execution_complete as a cosmetic-only event; if the SDK skips a terminal sub-agent event, a visible card still needs a fallback way to retire.
• .github/extensions/copilot-avatar/content/main.js can attach createSquadMicBoom() inside createAvatarInstance() for the root avatar, then flip it through updateRootSquadMicBoom() when window.setSquadContext() changes.
• .github/extensions/copilot-avatar/main.mjs can poll window.__copilotAvatarReady === true before calling window.setSquadContext(...), so the first Squad payload is not dropped during page bootstrap.
• .github/extensions/copilot-avatar/content/main.js should call updateRootSquadMicBoom(rootAvatar) inside initializeRootAvatar() so an already-latched squadRootMicActive flag still lights up the mic when the mesh appears.
• A live overlap snapshot can legitimately show Tony Stark and Howard the Duck together while the root card stays idle; verify the named sub-agent cards by display name, model row, and badge text before the overlap collapses.

SAM TTS Probe Patterns

• When probing a new TTS engine, assert: (1) speak() has an explicit engine === '<name>' branch that calls the engine function directly — not an else fallback; (2) the engine function is defined and uses the real synthesis path, not a placeholder that calls speakWebSpeech; (3) the engine voice selection persists via saveSettings and is restored to the module-level var BEFORE the populate-voices call.
• For SAM specifically: speakSam uses synthesizeSamAudio (custom Web Audio API formant engine) — NOT a sam-js npm/CDN call. SAM_PHONEME_DATA is the acoustic data table. SAM_VOICES holds 6 presets (sam/elf/cylon/vader/stuffy/gruff). All are self-contained in content/main.js.
• Assert populateSamVoices() uses option.selected = id === samVoice (not samVoiceSelect.value = samVoice after the fact) so the DOM reflects the restored value on first paint.
• Assert updateEngineUI has const isSam = ttsEngine === 'sam' and that ttsSamSection.classList.toggle('hidden', !isSam) plus ttsWebspeechSection.classList.toggle('hidden', isAiEngine || isSam) — all three toggles in one function.
• Assert canPreviewCurrentVoice has an explicit sam branch. Missing it means the Test button stays disabled even when SAM is selected and voices are loaded.
• Assert DEFAULT_SETTINGS.samVoice exists in main.mjs so fresh installs get a valid default without a saveSettings round-trip.

Anti-Patterns

• Approving a stale-state fix without checking both backend cache reset and webview avatar clearing.
• Approving a suppression fix that only clears ghosts on the next directive while letting same-turn no-completion agents pile up as idle cards.
• Verifying Squad names only with cast slugs while ignoring slot aliases that real events use.
• Keying visible-card coexistence only by runtime agentId and never checking whether two cards collapse to the same cast identity.
• Checking model wiring only on the root agent and missing per-subagent updates.
• Treating static code search as enough without at least one positive and one negative loadSquadContext() probe.
• Clearing the runtime payload but leaving payload.statusText || '● Squad ready' in the webview; explicit empty strings must survive the handoff when silence is the desired UI state.
• Signing off after regex/source checks without one live avatar-window poll; duplicate Howard the Duck-style ghosts and blank idle cards can slip through.
• Polling only after the overlap window ends and treating the missing cards as proof that concurrent visibility never happened.
• Detecting Squad a second time inside content/main.js and letting root-only Squad visuals leak into normal Copilot sessions.
• Treating webview.show() or the initial websocket as proof that window.setSquadContext already exists.
• Assuming window.setSquadContext() always runs after initializeRootAvatar(); on a fast webview connection the signal can arrive first, and the root chrome stays stale unless initialization reapplies the latched flag.
• Assuming the live avatar is already running the current project extension code without checking the loaded extension source or reloading it after local extension changes.
• Layering a second Squad accessory on top of the existing root flair instead of refactoring the old geometry out first.