debug-task

name	debug-task
description	Debug agent task execution infrastructure issues — wrong cwd, wrong files, wrong venv, browser startup failures, agent retry loops, skill loading failures

Debug Task Infra

Debug agent task execution infrastructure issues by analyzing agent logs.

Core Philosophy

Every agent failure, detour, or workaround is an infra/platform bug — not an agent problem.

When an agent:

• Tries a wrong file path then searches for the right one → catalog or path resolution bug
• Uses wrong CLI syntax then self-corrects → skill docs not loaded or incomplete
• Takes a screenshot but can't find/view it → tool integration bug
• Retries a command with different args → missing docs or unclear API
• Reflects "no failures" when there were failures → reflection prompt bug

Even if the agent eventually succeeds, each detour:

1. Wastes tokens and time
2. Signals a gap in the platform that WILL hit other tasks
3. Must be traced to a specific infra root cause and filed as a bug

Do NOT dismiss detours as "the agent will self-correct." Your job is to find every single failure step, trace it to a code/config/prompt root cause, and report it.

When to use

When a task execution shows symptoms like:

• Agent sees unexpected files or can't find expected ones
• Agent runs in wrong working directory
• Browser (Ziniao/Chrome) fails to start or takes multiple retries
• Task uses wrong Python environment
• Store context (bookmarks, browser config) missing from agent prompt
• Agent repeats same bash command 3+ times (infra issue, not agent fault)
• Agent repeats browser-open attempts (browser startup failure)
• Agent can't load skills (wrong skill path or skill not synced)
• Agent passes wrong arguments to tools (schema mismatch)
• Agent uses workarounds for things that should "just work"
• Agent's post-task reflection misses failures that clearly happened

Environment first: are you in WSL debugging a native-Windows server?

Before running ANY command below, figure out where the server actually runs. vibe-seller ships as a native-Windows install and as a Linux/WSL install, and the two do not share a data directory. Debugging the wrong one is the single biggest time-sink — you'll read a stale DB, grep empty logs, and "fix" a store that isn't the one serving traffic.

Detect the topology:

# The API answers, but is there a Python server process on the WSL side?
curl -s -m3 http://127.0.0.1:7777/api/auth/me   # 200 with a user  → a server is up
ps aux | grep -Ei 'uvicorn|app\.main' | grep -v grep   # empty → NOT served from WSL

# If empty, the server is the native-Windows process (WSL2 mirrored
# networking makes 127.0.0.1:7777 reach the Windows listener):
powershell.exe -NoProfile -Command "Get-Process python,pythonw -ErrorAction SilentlyContinue | Select Id,Path"
# → paths under C:\Users\<WinUser>\AppData\Local\Programs\VibeSeller\ confirm it

When the live server is native-Windows, everything relocates. The real runtime data root is /mnt/c/Users/<WinUser>/.vibe-seller/ (commonly <WinUser>=Administrator), NOT ~/.vibe-seller. Re-point every path in this doc:

This doc says	On a WSL→Windows box, use
~/.vibe-seller/data/vibe_seller.db	/mnt/c/Users/<WinUser>/.vibe-seller/data/vibe_seller.db
logs/backend_7777.log	/mnt/c/Users/<WinUser>/.vibe-seller/logs/
~/.vibe-seller/tasks/{id}/	/mnt/c/Users/<WinUser>/.vibe-seller/tasks/{id}/
~/.vibe-seller/bin/<slug>/browser-use	/mnt/c/Users/<WinUser>/.vibe-seller/bin/<slug>/browser-use
~/.vibe-seller/.claude/skills/	/mnt/c/Users/<WinUser>/.vibe-seller/.claude/skills/
app code (app/skills/…)	…/Programs/VibeSeller/.venv/Lib/site-packages/app/…

sqlite3 reads the Windows DB fine over /mnt/c. There is often ALSO a stale ~/.vibe-seller sandbox in WSL from earlier dev — it has a different stores table (decoy store names, wrong ids). If a store you expect is missing, or the ids don't match the live /api/stores response, you're reading the wrong DB.

Driving a store's browser-use wrapper from WSL

The per-store wrapper is generated by the Windows install with CRLF line endings, and it execs a Windows browser-use.EXE. Two failures bite immediately:

1. CRLF breaks WSL bash — execing it directly gives /usr/bin/env: 'bash\r': No such file or directory; running it via WSL bash gives set: pipefail: invalid option name. Do NOT dos2unix the file (it's regenerated on every server boot, and a sanitized copy then can't find the Windows .EXE). Instead run it through the install's bundled Git-for-Windows bash, which tolerates CRLF and resolves the Windows exec path:

   BASHEXE='/mnt/c/Users/<WinUser>/AppData/Local/Programs/VibeSeller/git/bin/bash.exe'
   WU_WIN='C:\Users\<WinUser>\.vibe-seller\bin\<slug>\browser-use'   # native path, backslashes
   TASK_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
   run(){ "$BASHEXE" -c "export VIBE_TASK_ID='$TASK_ID'; export PYTHONIOENCODING=utf-8 PYTHONUTF8=1; '$WU_WIN' $1"; }
   run "open https://sellercentral.amazon.<tld>/home"
   run "state"
   

2. GBK console → UnicodeEncodeError — the Windows Python console codec is GBK, so any page with Arabic/CJK text crashes state/eval with 'gbk' codec can't encode character. Always export PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 (shown above) before the wrapper call.

Downloads triggered through the CDP-proxied browser land in /mnt/c/Users/<WinUser>/.vibe-seller/downloads/<slug>/ (the proxy overrides Chrome's download dir per ziniao.py). Screenshots: pass a native Windows path (C:\...\downloads\<slug>\shot.png) to screenshot, then Read it from the /mnt/c equivalent.

For the browser-driving specifics (session rotation, wedged-daemon recovery, aux sessions) see the debug-store skill — the same WSL→Windows path/CRLF/UTF-8 rules apply there.

Restarting the native-Windows server

./restart.sh is WSL-only. To restart the Windows server, stop its pythonw/tray process and relaunch the installed app (see docs/windows-setup.md). Skills deploy by syncing repo app/skills/ into …/Programs/VibeSeller/.venv/Lib/site-packages/app/skills/; the server's skills_sync.fetch() copies them to …/.vibe-seller/.claude/skills/ at boot.

Debug methodology

RULE: Read agent logs BEFORE any conclusion

Every time this skill is invoked, you MUST read the actual agent debug logs before making any claim about what happened. Do not assume from file existence, code reading, or task_messages alone. The agent debug logs are the source of truth.

# 1. Find which run(s) happened — tasks can restart with different profiles!
grep "Starting agent.*{task_id}" logs/backend_7777.log

# 2. Get agent debug logs for the CORRECT run (match the date/time)
grep "AGENT_DEBUG.*{task_id}" logs/backend_7777.log | grep "{date}"

# 3. Find the transcript file (full session log, most detailed)
ls ~/.claude/projects/*{task_id}*/*.jsonl

# 4. Check if a skill body was actually loaded into context
#    (use strings unique to that skill's SKILL.md body)
grep -c "unique string from SKILL.md" <transcript.jsonl>

Common mistakes to avoid:

• Reading logs from the wrong run (task restarted with different profile)
• Checking transcript before the task finishes — skill loading may happen mid-task, not at start. Wait for task to complete before concluding.
• Assuming a skill is "loaded" because the file exists in the workspace
• Assuming slash_commands listing = skill content in LLM context (it doesn't — only metadata loads on discovery, body loads on trigger)
• Making claims about what the agent "saw" without transcript evidence
• Skipping the transcript file — it's the only way to confirm skill body loading

Step 0: Pick the task to debug

If the user didn't specify a task ID, find the most recent task from the last hour:

sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT id, status, substr(result,1,100), substr(error,1,100) \
   FROM tasks WHERE created_at > datetime('now', '-1 hour') \
   ORDER BY created_at DESC LIMIT 5;"

If exactly one task was active in the last hour, debug that one. If multiple, ask the user which one. If none, ask the user for a task ID.

Step 1: Pull ALL task messages

Read every message — not just errors. Detours hide in thinking messages where the agent says things like "let me try another approach" or "file doesn't exist, let me search."

# Full task log — read ALL of it, not just tail
sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT seq, role, content FROM task_messages \
   WHERE task_id='{task_id}' ORDER BY seq;"

Step 2: Walk through sequentially and flag EVERY detour

For each step, ask: "Did this step succeed on the first try?"

If not, classify the failure:

Failure Type	Signal in Logs	Root Cause Category
Wrong file path → search/glob → find correct path	Read error → Glob → Read success	Catalog/path resolution bug
Hallucinated CLI command → error → correct syntax	Bash error with usage/invalid choice message	Skill docs not effective enough
Tool output not usable → workaround	Screenshot returns bytes, agent searches for .png	Tool integration gap
File doesn't exist but agent expected it	Read error "File does not exist"	Catalog lists nonexistent file, or agent guessed
Duplicate table headers in catalog	Agent reads garbled catalog	Catalog generation bug
Browser open retried (even once)	>1 browser-use open to same URL	CDP proxy / Ziniao / wrapper script bug
Agent says "no failures" in reflection	Contradicts actual log	Reflection prompt doesn't force log review

Step 3: For each detour, trace to root cause

Every detour must map to ONE of these:

1. Catalog bug — wrong path, missing project/ prefix, duplicate headers, unlisted file
2. Skill docs bug — missing command, wrong syntax example, undocumented limitation
3. Tool integration bug — output not consumable, file not saved where expected
4. System prompt bug — unclear instructions, missing "ONLY read catalog files"
5. Workspace bug — missing symlinks, wrong isolation, files not synced
6. Reflection prompt bug — agent misses failures, doesn't save learnings

Step 4: Report findings

For each bug, provide:

• Seq range: which message steps were wasted
• What happened: agent action → error → workaround
• Steps wasted: count of unnecessary steps
• Root cause: specific code/file/prompt that caused it
• Fix location: exact file and what to change

Known bug patterns (from past investigations)

Catalog path resolution

The L1 catalog (app/knowledge/CATALOG.md) lists files like common/amazon-sites.md. These are synced to ~/.vibe-seller/knowledge/project/common/amazon-sites.md. But the store CATALOG.md copies L1 entries verbatim without adding the project/ prefix. From the agent's CWD, knowledge/ symlinks to ~/.vibe-seller/knowledge/, so the correct relative path is knowledge/project/common/amazon-sites.md — but the catalog says common/amazon-sites.md.

Fix: _filter_l1_for_store() in app/workspace/knowledge_sync.py should prepend project/ to L1 file paths in the store catalog, or the system prompt should tell the agent the base path.

Duplicate table header in store CATALOG

_filter_l1_for_store() returns a string starting with | File | Relevance | Summary | header. If _build_store_catalog() also adds a header, or if the function is called twice, the catalog gets a duplicate header row.

Check: app/workspace/knowledge_sync.py lines around _build_store_catalog and _filter_l1_for_store.

Agent hallucinates CLI commands (browser-use and others)

Agent invents CLI syntax that doesn't exist instead of using the commands documented in the loaded skill. Examples seen in the wild:

• browser-use scroll 10 (correct: browser-use scroll down --amount 500)
• browser-use get text without index (correct: browser-use get text <index>)
• browser-use screenshot without path then searching for .png files

How skill loading works (important for diagnosis): Skills go through 3 stages — discovery ≠ loading ≠ in context:

1. File exists — .claude/skills/ is copied (not symlinked) into the task workspace from ~/.vibe-seller/.claude/skills/ (app/workspace/manager.py ~line 710, shutil.copytree)
2. Discovered — Claude Code finds the SKILL.md via --add-dir and lists it in the init event's slash_commands array
3. Content in LLM context — the SKILL.md content is actually sent to the LLM as part of the prompt. This is the step that matters and the step that's hardest to verify.

CRITICAL: A skill appearing in slash_commands in the init event does NOT prove its content is in the LLM's context window. Claude Code may defer loading skill content until the skill is invoked or until a matching allowed-tools pattern fires.

IMPORTANT: browser-use SKILL.md is an upstream/official doc from the browser-use project. Do NOT modify it to fix agent behavior issues.

Diagnosis steps (in order of evidence strength):

1. Check the init event for the correct run (watch for task restarts!):

   # Find ALL starts — tasks can restart with different profiles
   grep "Starting agent.*{task_id}" logs/backend_7777.log
   # Then filter debug logs by the correct date/time
   grep "AGENT_DEBUG.*{task_id}.*system.*init" logs/backend_7777.log
   

   Look for slash_commands — does the skill name appear? If NO → file missing or --add-dir wrong → infra bug. If YES → skill was discovered but this does NOT mean body was loaded.

2. Check the transcript file (definitive evidence): Claude Code saves full transcripts at (replace <user> with your macOS / Linux username and <repo> with the repo dir): ~/.claude/projects/-Users-<user>-Desktop-<repo>-tasks-{task_id}/{session_id}.jsonl

   Search for unique strings from the SKILL.md body:

   # Find the transcript file
   ls ~/.claude/projects/*{task_id}*/*.jsonl
   
   # Search for SKILL.md body content (use strings unique to the skill)
   # For browser-use: "browser-use doctor", "browser-use tunnel",
   # "Browser Automation with browser-use CLI"
   grep -c "browser-use doctor" <transcript.jsonl>
   grep -c "Browser Automation with browser-use CLI" <transcript.jsonl>
   

   If count is 0 → skill body was NEVER loaded into context. If count > 0 → skill body was loaded.

3. Check if agent ever explicitly Read the skill file:

   sqlite3 ~/.vibe-seller/data/vibe_seller.db \
     "SELECT content FROM task_messages \
      WHERE task_id='{task_id}' AND content LIKE '%browser-use/SKILL.md%';"
   

Per ctx7 docs, Claude Code skill loading is 3-stage:

• Stage 1: metadata (name + description) loads immediately on discovery
• Stage 2: SKILL.md body loads when triggered by user queries
• Stage 3: references/examples load on demand

If skill metadata is discovered but body never loads, the triggering mechanism failed. Known causes:

• Duplicate skill discovery (task CWD is inside the git repo at ~/.vibe-seller/, so Claude Code finds .claude/skills/ at the git root AND in the task workspace copy) — check init event for duplicate (project) entries
• Skill directory structure issue (wrong path, symlink, missing files)
• Claude Code version-specific bugs in skill loading

Classification:

• Skill file missing from workspace → infra bug (workspace prep / skill sync)
• --add-dir not pointing to workspace → infra bug (claude_backend.py)
• Skill discovered but body not in context (transcript confirms) → skill loading/triggering bug (investigate Claude Code's trigger mechanism, possibly model-specific or language-specific)
• Skill body confirmed in context but agent ignored → LLM behavior

Ziniao/browser-use open must succeed on first call

The infra handles all browser lifecycle: CDP mux proxy, wrapper scripts, session management, auto-retry at the infra level. From the agent's perspective, browser-use open <url> is a one-shot operation that must always succeed on the first call.

Any retry by the agent = infra bug. This includes:

• Agent calls browser-use open more than once for the same URL
• Agent calls browser-use state and gets empty/error, then re-opens
• Agent sleeps and retries after open "just in case"

Root causes (all in infra, not agent):

• CDP mux proxy not routing correctly → cdp_mux_proxy.py
• Ziniao process not started before agent launch → browser/manager.py
• Wrapper script not injecting correct --session/--cdp-url → ~/.vibe-seller/bin/{store}/browser-use
• Port conflict between concurrent tasks → CDP proxy isolation bug
• Stale browser profile → wrapper script or profile management

Check:

# Count browser-use open calls (should be exactly 1 per URL)
sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT content FROM task_messages \
   WHERE task_id='{task_id}' AND role='tool_use' \
   AND content LIKE '%browser-use open%';"

# Check wrapper script
cat ~/.vibe-seller/bin/{store}/browser-use

# Check CDP proxy state
lsof -i | grep -i cdp

Agent reads files not in catalog

Agent guesses file names like seller-info.md that don't exist, despite having read the CATALOG.md which lists only existing files. The system prompt says to "Read the store catalog... Load only the files listed" but isn't forceful enough.

Fix: System prompt should say: "The catalog is the COMPLETE list of available files. Do NOT attempt to read files not listed in it."

Debug checklist (infrastructure)

1. Database state

sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT id, status, result, error FROM tasks ORDER BY created_at DESC LIMIT 5;"

2. Agent logs (backend logs)

Check logs/backend_<port>.log (e.g., logs/backend_7777.log):

# Real-time log following
tail -f logs/backend_7777.log | grep -Ei "error|fail|warn"

# Search for specific task
grep "task_id=xxx" logs/backend_7777.log

3. Working directory

ps aux | grep "claude.*{task_id}" | grep -oE "\-\-add-dir [^ ]+"

Expected: ~/.vibe-seller/tasks/{task_id}/

4. Workspace isolation

ls -la ~/.vibe-seller/tasks/{task_id}/
ls -la ~/.vibe-seller/tasks/{task_id}/.claude/skills/
readlink ~/.vibe-seller/tasks/{task_id}/knowledge

5. Browser startup

sqlite3 ~/.vibe-seller/data/vibe_seller.db "SELECT * FROM browser_sessions;"
cat ~/.vibe-seller/bin/{store-slug}/browser-use

6. Store context injection

sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT substr(content,1,500) FROM task_messages \
   WHERE task_id='{task_id}' AND seq=1;"

Key code paths

File	Responsibility
app/routers/tasks.py	_auto_run_task(), context injection, _build_store_context()
app/ai/claude_backend.py	Process spawn, cwd, env vars, venv activation
app/workspace/	workspace_manager.prepare_task_workspace(), isolation
app/workspace/knowledge_sync.py	Catalog generation (L1/L2/L3), path resolution
app/browser/manager.py	Browser config, wrapper scripts, startup logic
app/skills/	Built-in skills, skill manifest, skill sync
app/prompts/reflection.md	Post-task reflection prompt for knowledge capture
app/prompts/design_system.md	Planning agent instructions, catalog usage
~/.vibe-seller/	Runtime: data/, tasks/, .claude/skills/, bin/

Common root causes

Symptom	Likely cause	Fix location
Wrong CWD	prepare_task_workspace() not used or cwd not passed	claude_backend.py
Wrong venv	VIRTUAL_ENV not set or wrong PATH	claude_backend.py spawn
Wrong files	Workspace not isolated, agent sees parent/other tasks	workspace/ isolation
Browser fails	Startup race, port conflict, stale profile	browser/manager.py
Missing context	_build_store_context() returns empty/wrong	tasks.py context build
Skill not found	Skill not synced to ~/.vibe-seller/.claude/skills/	app/skills/sync.py
Hallucinated CLI syntax	Skill body not loaded — agent didn't invoke /skill	System prompt must tell agent to load skill before use
Tool output not usable	Agent can't consume base64/binary output	Skill docs + tool integration
Browser open retry (even once)	CDP proxy, Ziniao startup, or wrapper bug	cdp_mux_proxy.py, browser/manager.py, wrapper scripts
Catalog path wrong	L1 paths missing project/ prefix in L3 catalog	knowledge_sync.py
Duplicate catalog header	_filter_l1_for_store + _build_store_catalog double header	knowledge_sync.py
Agent guesses files	System prompt doesn't enforce catalog-only reads	design_system.md
Reflection misses failures	Prompt doesn't force sequential log review	reflection.md

Quick commands

# Latest backend errors
tail -100 logs/backend_7777.log | grep -Ei "error|fail|exception"

# Task workspace
find ~/.vibe-seller/tasks -type d -mtime -1 | head -5

# Running agents
ps aux | grep -E "claude|browser-use" | grep -v grep

# Browser sessions
sqlite3 ~/.vibe-seller/data/vibe_seller.db "SELECT * FROM browser_sessions;"

# Recent task messages with errors
sqlite3 ~/.vibe-seller/data/vibe_seller.db \
  "SELECT task_id, substr(content,1,150) FROM task_messages \
   WHERE content LIKE '%error%' OR content LIKE '%fail%' \
   ORDER BY created_at DESC LIMIT 10;"

# Check skill sync
diff -r app/skills/amazon-invoice ~/.vibe-seller/.claude/skills/amazon-invoice \
  2>/dev/null || echo "Skills differ or not synced"

# Check catalog paths resolve correctly
cat ~/.vibe-seller/stores/{slug}/CATALOG.md
ls ~/.vibe-seller/knowledge/project/common/  # L1 files land here