{
  "id": "page:docs-reference-troubleshooting",
  "_kind": "Page",
  "_file": "wiki/docs/reference/troubleshooting.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/reference/TROUBLESHOOTING.md",
    "sourceKind": "repo-docs",
    "title": "Babysitter Plugin Troubleshooting Guide",
    "displayName": "Babysitter Plugin Troubleshooting Guide",
    "slug": "docs/reference/troubleshooting",
    "articlePath": "wiki/docs/reference/TROUBLESHOOTING.md",
    "article": "\n# Babysitter Plugin Troubleshooting Guide\n\n> Comprehensive troubleshooting guide for the Babysitter plugin, organized by symptom.\n\n**Version:** 1.0.0\n**Last Updated:** 2026-02-03\n\n---\n\n## Table of Contents\n\n1. [Quick Diagnostic Commands](#quick-diagnostic-commands)\n2. [Run Stuck in \"Waiting\" State](#1-run-stuck-in-waiting-state)\n3. [Tasks Failing Silently](#2-tasks-failing-silently)\n4. [Hooks Not Executing](#3-hooks-not-executing)\n5. [Journal Corruption](#4-journal-corruption)\n6. [Session Loops Not Working](#5-session-loops-not-working)\n7. [Installation/Verification Failures](#6-installationverification-failures)\n8. [Permission Errors](#7-permission-errors)\n9. [FAQ](#faq)\n10. [Getting Help](#getting-help)\n\n---\n\n## Quick Diagnostic Commands\n\nRun these commands first to get an overview of your setup:\n\n```bash\n# Check installation status\n\n# Check runtime health\n\n# Check SDK CLI version\nnpx -y @a5c-ai/babysitter-sdk@latest --version\n\n# Check a specific run status\nCLI=\"npx -y @a5c-ai/babysitter-sdk@latest\"\n$CLI run:status <runId> --json\n\n# View recent events for a run\n$CLI run:events <runId> --limit 20 --reverse\n\n# List pending tasks\n$CLI task:list <runId> --pending --json\n```\n\n---\n\n## 2. Tasks Failing Silently\n\n### Symptoms\n\n- Run completes but expected work was not done\n- Tasks show `status: \"completed\"` but no output\n- No error messages visible\n- Process appears to skip steps\n\n### Diagnosis\n\n**Step 1: Check task status and result**\n\n```bash\nCLI=\"npx -y @a5c-ai/babysitter-sdk@latest\"\n\n# List all tasks\n$CLI task:list <runId> --json\n\n# Show specific task details\n$CLI task:show <runId> <effectId> --json\n```\n\n**Step 2: Inspect task logs**\n\n```bash\n# View task stdout\ncat .a5c/runs/<runId>/tasks/<effectId>/stdout.log\n\n# View task stderr\ncat .a5c/runs/<runId>/tasks/<effectId>/stderr.log\n\n# View task result\ncat .a5c/runs/<runId>/tasks/<effectId>/result.json | jq '.'\n```\n\n**Step 3: Check journal events for the task**\n\n```bash\n$CLI run:events <runId> --json | jq '.events[] | select(.effectId == \"<effectId>\")'\n```\n\n**Step 4: Verify task definition**\n\n```bash\ncat .a5c/runs/<runId>/tasks/<effectId>/task.json | jq '.'\ncat .a5c/runs/<runId>/tasks/<effectId>/inputs.json | jq '.'\n```\n\n### Solution\n\n**Missing logs:**\n\nIf stdout.log or stderr.log are empty or missing:\n1. Check that the task script exists and is executable\n2. Verify the entry path in the task definition is correct\n3. Ensure the working directory is correct\n\n**Task script errors:**\n\n1. Run the task script manually to see errors:\n   ```bash\n   node .a5c/runs/<runId>/code/main.js\n   ```\n2. Check for syntax errors or missing dependencies\n\n**Incorrect task definition:**\n\n1. Review the process file (`main.js`) for task definitions\n2. Verify task input/output paths are correct\n3. Check that `io.outputJsonPath` points to an existing directory\n\n**Re-run a failed task:**\n\n```bash\n# Mark the task as error to retry\n$CLI task:post <runId> <effectId> --status error --json\n\n# Then run the next iteration\n$CLI run:iterate <runId> --json --iteration <n>\n```\n\n### Prevention\n\n- Always check exit codes in task scripts\n- Log to both stdout and stderr appropriately\n- Use structured JSON output for task results\n- Add validation in process files before task execution\n- Test task scripts independently before integrating\n\n---\n\n## 3. Hooks Not Executing\n\n### Symptoms\n\n- Expected hook behavior does not occur\n- No log output from hooks\n- `on-run-start`, `on-task-complete`, etc. not triggering\n- Custom hooks are ignored\n\n### Diagnosis\n\n**Step 1: Verify hook is executable**\n\n```bash\nls -la .a5c/hooks/<hook-name>/\nls -la plugins/babysitter-unified/hooks/<hook-name>.sh\n```\n\nHooks must have the executable bit set (`-rwxr-xr-x`).\n\n**Step 2: Check hook discovery order**\n\nHooks are discovered in this priority order:\n1. `.a5c/hooks/<hook-name>/` (per-repo, highest priority)\n2. `~/.config/babysitter/hooks/<hook-name>/` (per-user)\n3. `plugins/babysitter-unified/hooks/<hook-name>.sh` (maintained plugin source)\n\n**Step 3: Test hook manually**\n\n```bash\n# Test with sample payload\necho '{\"runId\":\"test-123\",\"status\":\"completed\"}' | .a5c/hooks/on-run-complete/my-hook.sh\n```\n\n**Step 4: Check hook dispatcher**\n\n```bash\n# Test the maintained plugin hook entrypoint\necho '{\"session_id\":\"test-123\"}' | plugins/babysitter-unified/hooks/session-start.sh\n```\n\n**Step 5: Check hook registration (for Claude Code hooks)**\n\n```bash\ncat plugins/babysitter-unified/plugin.json | jq '.hooks'\n```\n\n### Solution\n\n**Make hooks executable:**\n\n```bash\nchmod +x .a5c/hooks/<hook-name>/*.sh\nchmod +x plugins/babysitter-unified/hooks/*.sh\n```\n\n**Fix hook script errors:**\n\n1. Check for syntax errors:\n   ```bash\n   bash -n .a5c/hooks/<hook-name>/my-hook.sh\n   ```\n2. Ensure the shebang is correct (`#!/bin/bash` or `#!/usr/bin/env bash`)\n3. Verify jq is installed (required for JSON parsing)\n\n**Correct hook output format:**\n\nHooks must:\n- Output JSON to stdout (for result data)\n- Output logs to stderr (not stdout, to avoid JSON parsing errors)\n- Exit with code 0 for success\n\nExample correct hook:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\nPAYLOAD=$(cat)\nRUN_ID=$(echo \"$PAYLOAD\" | jq -r '.runId')\n\n# Log to stderr (visible but not captured as result)\necho \"[my-hook] Processing run: $RUN_ID\" >&2\n\n# Output JSON to stdout\necho '{\"ok\": true}'\n\nexit 0\n```\n\n**Debug hook execution:**\n\nAdd debug logging to your hook:\n\n```bash\n#!/bin/bash\nset -euo pipefail\n\n# Debug: log payload to a file\ncat > /tmp/hook-debug-$$.json\n\n# Log execution\necho \"[DEBUG] Hook executed at $(date)\" >&2\necho \"[DEBUG] Payload saved to /tmp/hook-debug-$$.json\" >&2\n```\n\n### Prevention\n\n- Always test hooks manually before relying on them\n- Use `set -euo pipefail` at the start of hooks\n- Keep stdout for JSON output only\n- Log to stderr for debugging\n- Document hook purpose and expected payload\n\n---\n\n## 4. Journal Corruption\n\n### Symptoms\n\n- `run:status` returns errors or unexpected data\n- Run cannot be resumed\n- State cache is out of sync with journal\n- Events appear missing or duplicated\n\n### Diagnosis\n\n**Step 1: Verify journal integrity**\n\n```bash\nCLI=\"npx -y @a5c-ai/babysitter-sdk@latest\"\n\n# List all events (will error if corrupted)\n$CLI run:events <runId> --json\n```\n\n**Step 2: Check journal files directly**\n\n```bash\n# List journal files\nls -la .a5c/runs/<runId>/journal/\n\n# Validate each event file is valid JSON\nfor f in .a5c/runs/<runId>/journal/*.json; do\n  if ! jq '.' \"$f\" > /dev/null 2>&1; then\n    echo \"Corrupted: $f\"\n  fi\ndone\n```\n\n**Step 3: Check state cache**\n\n```bash\n# State cache should be rebuildable from journal\ncat .a5c/runs/<runId>/state/state.json | jq '.'\n```\n\n**Step 4: Check for incomplete writes**\n\n```bash\n# Look for partial/truncated files\nfind .a5c/runs/<runId>/journal/ -name \"*.json\" -size 0\n```\n\n### Solution\n\n**Rebuild state cache:**\n\nThe state cache (`state/state.json`) is derived from the journal and can be safely deleted:\n\n```bash\nrm .a5c/runs/<runId>/state/state.json\n\n# Next CLI command will rebuild it\n$CLI run:status <runId>\n```\n\n**Remove corrupted event files:**\n\nIf specific journal files are corrupted:\n\n1. Identify the corrupted file(s)\n2. Check if the event is critical (breakpoint release, task result, etc.)\n3. If non-critical, remove the file:\n   ```bash\n   rm .a5c/runs/<runId>/journal/<corrupted-file>.json\n   ```\n4. Rebuild state:\n   ```bash\n   rm .a5c/runs/<runId>/state/state.json\n   $CLI run:status <runId>\n   ```\n\n**Restore from backup:**\n\nIf the journal is heavily corrupted:\n\n1. If using git, restore from a previous commit:\n   ```bash\n   git checkout HEAD~1 -- .a5c/runs/<runId>/journal/\n   ```\n2. If you have backups, restore the journal directory\n\n**Start fresh:**\n\nIf recovery is not possible, create a new run:\n\n```bash\n$CLI run:create \\\n  --process-id <same-process-id> \\\n  --entry <same-entry> \\\n  --inputs <same-inputs>\n```\n\n### Prevention\n\n- Do not manually edit journal files\n- Use atomic file operations (the SDK does this automatically)\n- Back up critical runs before major operations\n- Use git to track run directories (journal is append-only and merge-friendly)\n- Monitor disk space to prevent incomplete writes\n\n---\n\n## 5. Session Loops Not Working\n\n### Symptoms\n\n- `/babysitter:babysit` command does not start a loop\n- Claude exits immediately instead of continuing\n- Iteration counter does not increment\n- Completion promise is not detected\n- \"No active loop\" message appears\n\n### Diagnosis\n\n**Step 1: Check session state file**\n\n```bash\n# State files are stored per session\nls -la ~/.a5c/state/\n\n# View state file contents\ncat ~/.a5c/state/<session-id>.md\n```\n\n**Step 2: Check stop hook logs**\n\n```bash\ncat /tmp/babysitter-stop-hook.log\n```\n\n**Step 3: Verify session ID is available**\n\nThe session ID is set by the SessionStart hook. Check if it was persisted:\n\n```bash\n# Check if AGENT_SESSION_ID is set\necho \"$AGENT_SESSION_ID\"\n```\n\n**Step 4: Check hook registration**\n\n```bash\ncat plugins/babysitter-unified/plugin.json | jq '.hooks'\n```\n\nShould include both `SessionStart` and `Stop` hooks.\n\n**Step 5: Test stop hook manually**\n\n```bash\necho '{\"session_id\":\"test-123\",\"transcript_path\":\"/tmp/test.jsonl\"}' | \\\n  plugins/babysitter-unified/hooks/stop.sh\n```\n\n### Solution\n\n**State file not created:**\n\nIf the state file is missing, the setup script may have failed:\n\n1. Check that `AGENT_SESSION_ID` is available:\n   ```bash\n   echo \"$AGENT_SESSION_ID\"\n   ```\n2. If not set, the SessionStart hook may have failed\n3. Check hook registration in `hooks.json`\n\n**Session ID not persisted:**\n\nBabysitter first looks for `AGENT_SESSION_ID`. If that is absent, the\nSessionStart hook can persist it through `CLAUDE_ENV_FILE` as a fallback.\nCheck:\n\n1. whether `AGENT_SESSION_ID` is already present in the current Claude session\n2. if not, whether `CLAUDE_ENV_FILE` is set\n3. whether that file is writable\n4. whether the hook is executable:\n   ```bash\n   chmod +x plugins/babysitter-unified/hooks/session-start.sh\n   ```\n\n**Iteration limit reached too quickly:**\n\nIf the loop stops due to \"iteration too fast\":\n\n```bash\n# Check the stop reason in logs\ngrep \"max_iterations_reached\\|completion_proof_matched\" /tmp/babysitter-stop-hook.log\n```\n\nThis protection triggers if iterations average under 15 seconds. Ensure your work takes meaningful time.\n\n**Completion promise not detected:**\n\nThe completion promise must match exactly:\n\n1. Check run status for `completionProof`:\n   ```bash\n   $CLI run:status <runId> --json | jq '.completionProof'\n   ```\n2. Verify output contains `<promise>SECRET</promise>` with exact match\n3. Whitespace is normalized but content must match\n\n**State file corruption:**\n\nIf the state file has invalid YAML:\n\n```bash\n# Mark the state file inactive to stop the loop\npython - <<'PY'\r\nfrom pathlib import Path\r\np = Path.home() / '.a5c' / 'state' / '<session-id>.md'\r\ns = p.read_text()\r\np.write_text(s.replace('active: true', 'active: false', 1))\r\nPY\n```\n\nThen start fresh with `/babysitter:babysit`.\n\n### Prevention\n\n- Always specify `--max-iterations` to prevent infinite loops\n- Do not manually edit state files\n- Ensure hooks are properly registered and executable\n- Test the stop hook independently before relying on it\n\n---\n\n## 6. Installation/Verification Failures\n\n### Symptoms\n\n- \"Command not found\" errors for babysitter CLI\n- Missing dependencies (Node.js, npm, jq)\n- Plugin structure errors\n\n### Diagnosis\n\n**Step 1: Run verification script**\n\n```bash\n```\n\n**Step 2: Check individual dependencies**\n\n```bash\n# Node.js (requires v18+)\nnode --version\n\n# npm\nnpm --version\n\n# git\ngit --version\n\n# jq (required for hooks)\njq --version\n```\n\n**Step 3: Check SDK CLI**\n\n```bash\nnpx -y @a5c-ai/babysitter-sdk@latest --version\n```\n\n**Step 4: Check plugin structure**\n\n```bash\nls -la plugins/babysitter-unified/\n# Should contain: hooks/, skills/, per-harness/, plugin.json, versions.json\n```\n\n### Solution\n\n**Install Node.js:**\n\nNode.js v18 or later is required.\n\n```bash\n# Download from https://nodejs.org/\n# Or use a version manager:\n\n# nvm (Linux/macOS)\nnvm install 18\nnvm use 18\n\n# fnm (cross-platform)\nfnm install 18\nfnm use 18\n```\n\n**Install jq:**\n\n```bash\n# macOS\nbrew install jq\n\n# Ubuntu/Debian\nsudo apt-get install jq\n\n# Windows (Chocolatey)\nchoco install jq\n\n# Windows (Scoop)\nscoop install jq\n```\n\n**Install/update SDK CLI:**\n\n```bash\n# Install globally\nnpm install -g @a5c-ai/babysitter-sdk@latest\n\n# Or use npx (no install required)\nnpx -y @a5c-ai/babysitter-sdk@latest --version\n```\n\n**Fix plugin structure:**\n\nIf directories are missing, re-clone the plugin:\n\n```bash\ngit clone https://github.com/a5c-ai/babysitter.git /tmp/babysitter-fresh\nnpm --prefix /tmp/babysitter-fresh install\nnpm --prefix /tmp/babysitter-fresh run generate:plugins\n```\n\n**Clear npx cache:**\n\nIf npx returns stale versions:\n\n```bash\nnpx --cache clear\n\n# Or specify latest explicitly\nnpx -y @a5c-ai/babysitter-sdk@latest --version\n```\n\n### Prevention\n\n- Use a Node.js version manager (nvm, fnm)\n- Pin SDK version in your project (optional)\n- Keep the plugin updated with git pull\n\n---\n\n## 7. Permission Errors\n\n### Symptoms\n\n- \"Permission denied\" when running hooks\n- Cannot create state files or directories\n- Cannot write to runs directory\n- Hook scripts fail with permission errors\n\n### Diagnosis\n\n**Step 1: Check hook permissions**\n\n```bash\nls -la plugins/babysitter-unified/hooks/*.sh\nls -la .a5c/hooks/**/*.sh\n```\n\nHooks should have execute permission (`-rwxr-xr-x` or at least `-rwx------`).\n\n**Step 2: Check directory permissions**\n\n```bash\n# Runs directory\nls -la .a5c/runs/\n\n# State directory\nls -la ~/.a5c/state/\n\n# Plugin directory\nls -la plugins/babysitter-unified/\n```\n\n**Step 3: Check file ownership**\n\n```bash\nls -la .a5c/\n```\n\nEnsure the current user owns the directories.\n\n**Step 4: Test write access**\n\n```bash\n# Test runs directory\ntouch .a5c/runs/.write-test && rm .a5c/runs/.write-test\n\n# Test state directory\ntouch ~/.a5c/state/.write-test && rm ~/.a5c/state/.write-test\n```\n\n### Solution\n\n**Fix hook permissions:**\n\n```bash\n# Make all hooks executable\nchmod +x plugins/babysitter-unified/hooks/*.sh\nchmod +x .a5c/hooks/**/*.sh\n```\n\n**Fix directory permissions:**\n\n```bash\n# Fix runs directory\nchmod 755 .a5c\nchmod 755 .a5c/runs\n\n# Fix state directory\nchmod 755 ~/.a5c/state\n\n# Create state directory if missing\nmkdir -p ~/.a5c/state\nchmod 755 ~/.a5c/state\n```\n\n**Fix ownership:**\n\n```bash\n# Change ownership to current user\nsudo chown -R $(whoami) .a5c/\nsudo chown -R $(whoami) plugins/babysitter-unified/\n```\n\n**SELinux/AppArmor issues (Linux):**\n\nIf using SELinux or AppArmor:\n\n```bash\n# Check if SELinux is blocking\nausearch -m avc -ts recent\n\n# Temporarily set permissive mode (for testing)\nsudo setenforce 0\n```\n\n**Windows-specific:**\n\nOn Windows (Git Bash/WSL):\n\n```bash\n# Git Bash may not preserve execute bits\n# Mark hooks as executable in git\ngit update-index --chmod=+x plugins/babysitter-unified/hooks/*.sh\n```\n\n### Prevention\n\n- Set correct permissions when creating new hooks\n- Use version control to preserve permissions\n- Create directories with appropriate permissions from the start\n- On Windows, consider using WSL for full Unix permissions support\n\n---\n\n## FAQ\n\n### General Questions\n\n**Q: How do I check if babysitter is properly installed?**\n\nA: Run the verification script:\n```bash\n```\n\n**Q: What Node.js version is required?**\n\nA: Node.js v18 or later is required. Check with `node --version`.\n\n**Q: How do I update the SDK CLI?**\n\nA:\n```bash\nnpm install -g @a5c-ai/babysitter-sdk@latest\n# Or use npx which always gets latest:\nnpx -y @a5c-ai/babysitter-sdk@latest\n```\n\n### Run Management\n\n**Q: How do I cancel a running orchestration?**\n\nA: You can:\n1. Stop the iteration loop (Ctrl+C if running in terminal)\n2. Delete the session state file for in-session loops:\n   ```bash\n   python - <<'PY'\r\nfrom pathlib import Path\r\np = Path.home() / '.a5c' / 'state' / '<session-id>.md'\r\ns = p.read_text()\r\np.write_text(s.replace('active: true', 'active: false', 1))\r\nPY\n   ```\n\n**Q: How do I resume a failed run?**\n\nA: Use the run:iterate command to continue:\n```bash\n$CLI run:iterate <runId> --json --iteration <next-iteration>\n```\n\n**Q: How do I view the full history of a run?**\n\nA:\n```bash\n$CLI run:events <runId> --limit 100 --json | jq '.events'\n```\n\n**Q: Can I run multiple orchestrations in parallel?**\n\nA: Yes. Each run has its own directory and state. For in-session loops, each Claude Code session has isolated state via `AGENT_SESSION_ID`.\n\n### Hooks\n\n**Q: Why is my custom hook not being called?**\n\nA: Check these in order:\n1. Hook is in the correct directory (`.a5c/hooks/<hook-name>/`)\n2. Hook file ends with `.sh`\n3. Hook is executable (`chmod +x`)\n4. Hook outputs valid JSON to stdout\n\n**Q: How do I debug a hook?**\n\nA: Test it manually:\n```bash\necho '{\"runId\":\"test\"}' | ./my-hook.sh\n```\nAdd debug logging to stderr:\n```bash\necho \"[DEBUG] My message\" >&2\n```\n\n**Q: What hooks are available?**\n\nA:\n- **SDK Lifecycle:** `on-run-start`, `on-run-complete`, `on-run-fail`, `on-task-start`, `on-task-complete`, `on-iteration-start`, `on-iteration-end`, `on-step-dispatch`\n- **Process-Level:** `pre-commit`, `pre-branch`, `post-planning`, `on-score`, `on-breakpoint`\n\n### Session Loops\n\n**Q: How do I stop an in-session loop?**\n\nA:\n1. Use `--max-iterations` to set a limit\n2. Output the completion proof: `<promise>SECRET</promise>`\n3. Mark the state file inactive:\n   ```bash\n   python - <<'PY'\r\nfrom pathlib import Path\r\np = Path.home() / '.a5c' / 'state' / '<session-id>.md'\r\ns = p.read_text()\r\np.write_text(s.replace('active: true', 'active: false', 1))\r\nPY\n   ```\n\n**Q: Where is the session state stored?**\n\nA: `~/.a5c/state/${AGENT_SESSION_ID}.md`\n\n**Q: What happens if I close Claude Code during a loop?**\n\nA: The state file remains. When you restart, the loop will not resume automatically. You can:\n- Mark the state file inactive to clear hook blocking while retaining recovery context\n- Start a new loop with `/babysitter:babysit`\n\n### Troubleshooting Commands\n\n**Q: What is the most useful diagnostic command?**\n\nA: The health check provides a comprehensive overview:\n```bash\n```\n\n**Q: How do I get verbose output from the CLI?**\n\nA:\n```bash\n$CLI run:status <runId> --verbose --json\n```\n\n**Q: How do I check what tasks are blocking a run?**\n\nA:\n```bash\n$CLI task:list <runId> --pending --json | jq '.tasks'\n```\n\n---\n\n## Getting Help\n\n### Documentation\n\n- **Plugin Specification:** `plugins/babysitter-unified/plugin.json`\n- **Hooks Guide:** `plugins/babysitter-unified/skills/babysit/SKILL.md`\n- **SDK Reference:** `packages/sdk/sdk.md`\n- **In-Session Loops:** `packages/sdk/src/cli/commands/instructions.ts`\n\n### CLI Help\n\n```bash\nnpx -y @a5c-ai/babysitter-sdk@latest --help\nnpx -y @a5c-ai/babysitter-sdk@latest run:create --help\nnpx -y @a5c-ai/babysitter-sdk@latest task:post --help\n```\n\n### Useful Diagnostic Data to Collect\n\nWhen reporting issues, collect:\n\n1. **System info:**\n   ```bash\n   ```\n\n2. **Health check:**\n   ```bash\n   ```\n\n3. **Run status (if applicable):**\n   ```bash\n   $CLI run:status <runId> --json\n   ```\n\n4. **Recent events:**\n   ```bash\n   $CLI run:events <runId> --limit 20 --reverse --json\n   ```\n\n5. **Stop hook logs (for session loops):**\n   ```bash\n   cat /tmp/babysitter-stop-hook.log\n   ```\n\n### Report Issues\n\n- GitHub Issues: https://github.com/a5c-ai/babysitter/issues\n- Include: CLI version, error output, diagnostic data from above\n\n---\n\n**Document Metadata:**\n- Created: 2026-02-03\n- Version: 1.0.0\n- Component: Babysitter Plugin Troubleshooting Guide\n- Status: Production\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-reference",
      "to": "page:docs-reference-troubleshooting",
      "kind": "contains_page"
    }
  ]
}