feat: add agent connection diagnostics, JSONL parser resilience (#183)

* feat: add agent connection diagnostics, JSONL parser resilience, and path encoding fuzzy matching

* fix: simplify file watching to single poll, drop unreliable fs.watch/fs.watchFile

* docs: add rebase check to PR template

* docs: add Debug View guidance to bug report template

* fix: patch VS Code product.json to bypass Updating in progress in e2e tests

Author: florintimbuc

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -44,14 +44,23 @@ body:
     id: screenshots
     attributes:
       label: "Screenshots / GIFs"
-      description: "If applicable, add screenshots or screen recordings."
+      description: "If applicable, add screenshots or screen recordings. For agent tracking issues (stuck on idle, not spawning), include a screenshot of the **Debug View**: in the Pixel Agents panel, click the gear icon (Settings) and toggle Debug View. This shows JSONL connection status, lines parsed, and file paths. **Note:** paths may contain your username -- redact anything sensitive before posting."
 
   - type: input
     id: vscode-version
     attributes:
       label: "VS Code version"
       description: "Run 'Help > About' to find your version."
-      placeholder: "e.g., 1.109.0"
+      placeholder: "e.g., 1.112.0"
+    validations:
+      required: true
+
+  - type: input
+    id: claude-code-version
+    attributes:
+      label: "Claude Code CLI version"
+      description: "Run `claude --version` in your terminal."
+      placeholder: "e.g., 2.1.78"
     validations:
       required: true
 
@@ -63,12 +72,13 @@ body:
         - Windows
         - macOS
         - Linux
+        - WSL2
     validations:
       required: true
 
   - type: textarea
     id: logs
     attributes:
       label: "Logs"
-      description: "Open Developer Tools (Help > Toggle Developer Tools) and paste any relevant console output."
+      description: "If running from source (F5), open **View > Debug Console** and paste any lines containing `[Pixel Agents]`. Otherwise, open **Help > Toggle Developer Tools > Console** and paste relevant output. **Note:** logs may contain file paths with your username -- redact anything sensitive before posting."
       render: shell

.github/pull_request_template.md

@@ -8,7 +8,7 @@
 - [ ] Refactor / code cleanup
 - [ ] Documentation
 - [ ] CI / build
-- [ ] Other: ___
+- [ ] Other: ...
 
 ## Related issues
 <!-- Link related issues: Closes #123, Fixes #456 -->
@@ -17,9 +17,7 @@
 <!-- Required for UI changes. Delete this section if not applicable. -->
 
 ## Test plan
-<!-- Check what applies, add your own test steps -->
-- [ ] PR targets `main` branch
-- [ ] `npm run build` passes locally
+<!-- Add your own test steps -->
+- [ ] Rebased on latest `main`
 - [ ] Tested in Extension Development Host (F5)
-- [ ] No inline constants (all in `src/constants.ts` or `webview-ui/src/constants.ts`)
-- [ ] UI follows pixel art style (sharp corners, solid borders, pixel font)
+- [ ] ...

README.md

@@ -119,6 +119,13 @@ The webview runs a lightweight game loop with canvas rendering, BFS pathfinding,
 - **Heuristic-based status detection** — Claude Code's JSONL transcript format does not provide clear signals for when an agent is waiting for user input or when it has finished its turn. The current detection is based on heuristics (idle timers, turn-duration events) and often misfires — agents may briefly show the wrong status or miss transitions.
 - **Linux/macOS tip** — if you launch VS Code without a folder open (e.g. bare `code` command), agents will start in your home directory. This is fully supported; just be aware your Claude sessions will be tracked under `~/.claude/projects/` using your home directory as the project root.
 
+## Troubleshooting
+
+If your agent appears stuck on idle or doesn't spawn:
+
+1. **Debug View** — In the Pixel Agents panel, click the gear icon (Settings), then toggle **Debug View**. This shows connection diagnostics per agent: JSONL file status, lines parsed, last data timestamp, and file path. If you see "JSONL not found", the extension can't locate the session file.
+2. **Debug Console** — If you're running from source (Extension Development Host via F5), open VS Code's **View > Debug Console**. Search for `[Pixel Agents]` to see detailed logs: project directory resolution, JSONL polling status, path encoding mismatches, and unrecognized JSONL record types.
+
 ## Where This Is Going
 
 The long-term vision is an interface where managing AI agents feels like playing the Sims, but the results are real things built.

e2e/global-setup.ts

@@ -5,6 +5,63 @@ import path from 'path';
 export const VSCODE_CACHE_DIR = path.join(__dirname, '../.vscode-test');
 export const VSCODE_PATH_FILE = path.join(VSCODE_CACHE_DIR, 'vscode-executable.txt');
 
+/**
+ * On Windows, VS Code checks for an InnoSetup mutex (`win32MutexName + "-updating"`)
+ * at startup. If the host machine's VS Code installer is running (e.g. a pending
+ * "Restart to Update"), the mutex is held and ALL VS Code instances — including our
+ * test archive — refuse to start with "Code is currently being updated".
+ *
+ * The check in main.js is:
+ *   if (!(isWindows && product.win32MutexName && product.win32VersionedUpdate)) return false;
+ *
+ * Removing `win32VersionedUpdate` from product.json makes the check short-circuit,
+ * so the test instance launches regardless of installer state. This is safe because
+ * the test archive is not managed by InnoSetup and never needs update coordination.
+ */
+function patchProductJsonForWindows(vscodePath: string): void {
+  if (process.platform !== 'win32') return;
+
+  // vscodePath points to Code.exe — product.json is in the resources/app dir
+  const vscodeDir = path.dirname(vscodePath);
+  const candidates = fs
+    .readdirSync(vscodeDir)
+    .filter((d) => {
+      try {
+        return fs.statSync(path.join(vscodeDir, d)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((d) => path.join(vscodeDir, d, 'resources', 'app', 'product.json'))
+    .filter((p) => fs.existsSync(p));
+
+  for (const productJsonPath of candidates) {
+    try {
+      const product = JSON.parse(fs.readFileSync(productJsonPath, 'utf8'));
+      let patched = false;
+
+      if (product.win32VersionedUpdate) {
+        delete product.win32VersionedUpdate;
+        patched = true;
+      }
+      // Also check nested objects (e.g. "tunnelApplicationConfig")
+      for (const key of Object.keys(product)) {
+        if (typeof product[key] === 'object' && product[key]?.win32VersionedUpdate) {
+          delete product[key].win32VersionedUpdate;
+          patched = true;
+        }
+      }
+
+      if (patched) {
+        fs.writeFileSync(productJsonPath, JSON.stringify(product, null, '\t') + '\n', 'utf8');
+        console.log(`[e2e] Patched product.json to skip InnoSetup mutex check: ${productJsonPath}`);
+      }
+    } catch (err) {
+      console.warn(`[e2e] Failed to patch product.json at ${productJsonPath}:`, err);
+    }
+  }
+}
+
 export default async function globalSetup(): Promise<void> {
   console.log('[e2e] Ensuring VS Code is downloaded...');
   const vscodePath = await downloadAndUnzipVSCode({
@@ -13,6 +70,8 @@ export default async function globalSetup(): Promise<void> {
   });
   console.log(`[e2e] VS Code executable: ${vscodePath}`);
 
+  patchProductJsonForWindows(vscodePath);
+
   fs.mkdirSync(VSCODE_CACHE_DIR, { recursive: true });
   fs.writeFileSync(VSCODE_PATH_FILE, vscodePath, 'utf8');
 }

e2e/helpers/launch.ts

@@ -141,6 +141,9 @@ export async function launchVSCode(testTitle: string): Promise<VSCodeSession> {
     '--skip-release-notes',
     '--skip-welcome',
     '--no-sandbox',
+    // Prevent "Code is currently being updated" errors when the host VS Code
+    // is mid-update — the test instance must not participate in update checks.
+    '--disable-updates',
     // Disable GPU acceleration: prevents Electron GPU-sandbox stalls in headless
     // CI environments (required on macOS arm64 runners, harmless elsewhere).
     '--disable-gpu',

src/PixelAgentsViewProvider.ts

@@ -246,6 +246,32 @@ export class PixelAgentsViewProvider implements vscode.WebviewViewProvider {
           }
         })();
         sendExistingAgents(this.agents, this.context, this.webview);
+      } else if (message.type === 'requestDiagnostics') {
+        // Send connection diagnostics for all agents to the Debug View
+        const diagnostics: Array<Record<string, unknown>> = [];
+        for (const [, agent] of this.agents) {
+          let jsonlExists = false;
+          let fileSize = 0;
+          try {
+            const stat = fs.statSync(agent.jsonlFile);
+            jsonlExists = true;
+            fileSize = stat.size;
+          } catch {
+            /* file doesn't exist */
+          }
+          diagnostics.push({
+            id: agent.id,
+            projectDir: agent.projectDir,
+            projectDirExists: fs.existsSync(agent.projectDir),
+            jsonlFile: agent.jsonlFile,
+            jsonlExists,
+            fileSize,
+            fileOffset: agent.fileOffset,
+            lastDataAt: agent.lastDataAt,
+            linesProcessed: agent.linesProcessed,
+          });
+        }
+        this.webview?.postMessage({ type: 'agentDiagnostics', agents: diagnostics });
       } else if (message.type === 'openSessionsFolder') {
         const projectDir = getProjectDirPath();
         if (projectDir && fs.existsSync(projectDir)) {

src/agentManager.ts

@@ -24,6 +24,34 @@ export function getProjectDirPath(cwd?: string): string {
   const dirName = workspacePath.replace(/[^a-zA-Z0-9-]/g, '-');
   const projectDir = path.join(os.homedir(), '.claude', 'projects', dirName);
   console.log(`[Pixel Agents] Project dir: ${workspacePath} → ${dirName}`);
+
+  // Verify the directory exists; if not, try fuzzy matching against existing dirs
+  if (!fs.existsSync(projectDir)) {
+    const projectsRoot = path.join(os.homedir(), '.claude', 'projects');
+    try {
+      if (fs.existsSync(projectsRoot)) {
+        const candidates = fs.readdirSync(projectsRoot);
+        // Try case-insensitive match (handles Windows drive letter casing)
+        const lowerDirName = dirName.toLowerCase();
+        const match = candidates.find((c) => c.toLowerCase() === lowerDirName);
+        if (match && match !== dirName) {
+          const matchedDir = path.join(projectsRoot, match);
+          console.log(
+            `[Pixel Agents] Project dir not found, using case-insensitive match: ${dirName} → ${match}`,
+          );
+          return matchedDir;
+        }
+        if (!match) {
+          console.warn(
+            `[Pixel Agents] Project dir does not exist: ${projectDir}. ` +
+              `Available dirs (${candidates.length}): ${candidates.slice(0, 5).join(', ')}${candidates.length > 5 ? '...' : ''}`,
+          );
+        }
+      }
+    } catch {
+      // Ignore scan errors
+    }
+  }
   return projectDir;
 }
 
@@ -88,6 +116,9 @@ export async function launchNewTerminal(
     isWaiting: false,
     permissionSent: false,
     hadToolsInTurn: false,
+    lastDataAt: 0,
+    linesProcessed: 0,
+    seenUnknownRecordTypes: new Set(),
     folderName,
   };
 
@@ -113,11 +144,14 @@ export async function launchNewTerminal(
   );
 
   // Poll for the specific JSONL file to appear
+  let pollCount = 0;
+  console.log(`[Pixel Agents] Agent ${id}: waiting for JSONL at ${agent.jsonlFile}`);
   const pollTimer = setInterval(() => {
+    pollCount++;
     try {
       if (fs.existsSync(agent.jsonlFile)) {
         console.log(
-          `[Pixel Agents] Agent ${id}: found JSONL file ${path.basename(agent.jsonlFile)}`,
+          `[Pixel Agents] Agent ${id}: found JSONL file ${path.basename(agent.jsonlFile)} (after ${pollCount}s)`,
         );
         clearInterval(pollTimer);
         jsonlPollTimers.delete(id);
@@ -132,6 +166,27 @@ export async function launchNewTerminal(
           webview,
         );
         readNewLines(id, agents, waitingTimers, permissionTimers, webview);
+      } else if (pollCount === 10) {
+        // After 10s of polling, warn with path details to help diagnose path encoding mismatches
+        const dirExists = fs.existsSync(projectDir);
+        let dirContents = '';
+        if (dirExists) {
+          try {
+            const files = fs.readdirSync(projectDir).filter((f) => f.endsWith('.jsonl'));
+            dirContents =
+              files.length > 0
+                ? `Dir has ${files.length} JSONL file(s): ${files.slice(0, 3).join(', ')}${files.length > 3 ? '...' : ''}`
+                : 'Dir exists but has no JSONL files';
+          } catch {
+            dirContents = 'Dir exists but unreadable';
+          }
+        } else {
+          dirContents = 'Dir does not exist';
+        }
+        console.warn(
+          `[Pixel Agents] Agent ${id}: JSONL file not found after 10s. ` +
+            `Expected: ${agent.jsonlFile}. ${dirContents}`,
+        );
       }
     } catch {
       /* file may not exist yet */
@@ -168,11 +223,6 @@ export function removeAgent(
     clearInterval(pt);
   }
   pollingTimers.delete(agentId);
-  try {
-    fs.unwatchFile(agent.jsonlFile);
-  } catch {
-    /* ignore */
-  }
 
   // Cancel timers
   cancelWaitingTimer(agentId, waitingTimers);
@@ -244,6 +294,9 @@ export function restoreAgents(
       isWaiting: false,
       permissionSent: false,
       hadToolsInTurn: false,
+      lastDataAt: 0,
+      linesProcessed: 0,
+      seenUnknownRecordTypes: new Set(),
       folderName: p.folderName,
     };
 

src/constants.ts

@@ -1,6 +1,6 @@
 // ── Timing (ms) ──────────────────────────────────────────────
 export const JSONL_POLL_INTERVAL_MS = 1000;
-export const FILE_WATCHER_POLL_INTERVAL_MS = 1000;
+export const FILE_WATCHER_POLL_INTERVAL_MS = 500;
 export const PROJECT_SCAN_INTERVAL_MS = 1000;
 export const TOOL_DONE_DELAY_MS = 300;
 export const PERMISSION_TIMER_DELAY_MS = 7000;