Menu
Debug agent task execution infrastructure issues — wrong cwd, wrong files, wrong venv, browser startup failures, agent retry loops, skill loading failures
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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 agent task execution infrastructure issues by analyzing agent logs.
Every agent failure, detour, or workaround is an infra/platform bug — not an agent problem.
When an agent:
Even if the agent eventually succeeds, each detour:
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 a task execution shows symptoms like:
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.
browser-use wrapper from WSLThe 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:
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"
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.
./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.
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:
slash_commands listing = skill content in LLM context (it doesn't —
only metadata loads on discovery, body loads on trigger)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.
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;"
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 |
Every detour must map to ONE of these:
project/ prefix, duplicate headers, unlisted fileFor each bug, provide:
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.
_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 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 filesHow skill loading works (important for diagnosis): Skills go through 3 stages — discovery ≠ loading ≠ in context:
.claude/skills/ is copied (not symlinked) into the
task workspace from ~/.vibe-seller/.claude/skills/
(app/workspace/manager.py ~line 710, shutil.copytree)--add-dir and lists
it in the init event's slash_commands arrayCRITICAL: 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):
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.
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.
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:
If skill metadata is discovered but body never loads, the triggering mechanism failed. Known causes:
~/.vibe-seller/, so Claude Code finds .claude/skills/ at the
git root AND in the task workspace copy) — check init event for
duplicate (project) entriesClassification:
--add-dir not pointing to workspace → infra bug (claude_backend.py)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:
browser-use open more than once for the same URLbrowser-use state and gets empty/error, then re-opensRoot causes (all in infra, not agent):
cdp_mux_proxy.pybrowser/manager.py--session/--cdp-url → ~/.vibe-seller/bin/{store}/browser-useCheck:
# 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 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."
sqlite3 ~/.vibe-seller/data/vibe_seller.db \
"SELECT id, status, result, error FROM tasks ORDER BY created_at DESC LIMIT 5;"
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
ps aux | grep "claude.*{task_id}" | grep -oE "\-\-add-dir [^ ]+"
Expected: ~/.vibe-seller/tasks/{task_id}/
ls -la ~/.vibe-seller/tasks/{task_id}/
ls -la ~/.vibe-seller/tasks/{task_id}/.claude/skills/
readlink ~/.vibe-seller/tasks/{task_id}/knowledge
sqlite3 ~/.vibe-seller/data/vibe_seller.db "SELECT * FROM browser_sessions;"
cat ~/.vibe-seller/bin/{store-slug}/browser-use
sqlite3 ~/.vibe-seller/data/vibe_seller.db \
"SELECT substr(content,1,500) FROM task_messages \
WHERE task_id='{task_id}' AND seq=1;"
| 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/ |
| 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 |
# 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
Amazon listing CRUD via the category flat-file (Add Products via Upload). Create a variation family (parent + colour/size children), update attributes, change parent-child relationships, and delete SKUs — all in one template round trip. Also covers the end-to-end sourcing flow: a supplier link (e.g. 1688) → extract product data → local GPU-free OCR of detail images → generate title / bullet points / description → bilingual review with the user → propose the parent-child structure → fill the template → upload → read the processing report. Load this BEFORE any browser-use action on sellercentral.amazon.<tld>/listing/upload or when the task is to create / edit / delete a listing from a product link.
Common Amazon Seller Central / advertising-console mechanics — marketplace TLD map; version-aware navigation (New Seller Central 'NGS' vs classic, navigate by direct URL); sign-in as a challenge LOOP with Ziniao auto-fill of password / OTP (紫鸟验证码服务) / hosted passkey (已托管账号Passkey, native overlay → coordinate-click), Ziniao-stored-else-human rule; ad-console vs seller-central account caveat; capture rule. Prerequisite: every other amazon-* skill (amazon-ads, amazon-reports, amazon-invoice, amazon-listing / amazon-fbn / etc.) expects this loaded for cross-cutting auth and navigation patterns.
Save the workflow you just carried out as a reusable skill — OR update an existing skill — whenever the user asks to remember, reuse, or amend it. Triggers include "把这个任务的流程保存为技能", "save this workflow as a skill", "save to skill", "remember how to do this", "turn this into a skill", "next time do it the same way", AND update/extend phrasings like "update that skill", "extend the skill", "add this step to the skill", "make the skill also remember to…", "更新这个技能", "把这一步加到技能里", "让技能也记住…". Search the existing skills first, then EXTEND the one that already covers this workflow or CREATE a new one — never duplicate. Skills are saved/extended ONLY through the vibe_seller_save_skill MCP tool (the built-in Write/Edit tools do not persist skill files); they then auto-load for future tasks.
Common noon Seller Center mechanics — login (OTP auto-fetch), page-structure URL map, My Catalog read access, common modals, button-click patterns, project-ID discovery. Prerequisite: every other noon-* skill (noon-listing, noon-fbn, noon-exports, noon-ads) expects this loaded for auth and shared UI patterns.
Amazon Sponsored Products / Sponsored Brands / Sponsored Display ads + Coupons on Seller Central / advertising console. ONE catalog covering BOTH mechanics (URLs, click paths, modal patterns, kat-* component gotchas, field input ranges) AND workflows (tuning existing campaigns, weekly review, search-term harvest, ACOS improvement). Load this skill BEFORE any browser-use action that creates, edits, captures, archives, or downloads campaigns / ad-groups / keywords / product targets / coupons on amazon.<tld> or advertising.amazon.<tld>. The catalog below points to topical references — load whichever ones the task needs. Defaults to last 30 days for tuning analysis but accepts any user-specified window.
MUST load BEFORE running any browser-use command. This is the only bridge between the agent and the browser — browser-use 0.13 has NO subcommands (open/click/state are gone); you drive the browser by piping Python helper code via a heredoc. Contains the helper API, wrapper rules, session management, and store-task restrictions. Without this skill, browser commands will fail.