Troubleshooting

Use this page to isolate failures quickly.

Fast Triage Sequence

1. Verify current workspace path.
2. Verify the failing feature's required directory/command is valid.
3. Check local diagnostics and in-card error state.
4. Re-run with a minimal prompt/todo item.
5. Expand scope only after baseline success.

Workspace Resolves To Wrong Path

Symptom:

• Workspace appears as a temp path like /var/folders/.../agent-observer-smoke-*

Fix:

1. Set default workspace directory to the intended repo root.
2. Reopen folder in Explorer.
3. Confirm scope indicator before sending chat prompts.

Renderer Crash / Blue Screen

1. Restart the app.
2. Reopen one workspace only.
3. Reproduce with minimal actions.
4. Check diagnostics logs for render-process-gone or related errors.

Search Missing Expected Files

1. Confirm workspace root is correct.
2. Confirm target path is inside workspace.
3. Check macOS privacy permissions for folder access.
4. Re-run search with exact file name.

Scheduled Action Not Running

1. Confirm task is enabled.
2. Validate cron has 5 fields.
3. Confirm app was open at trigger time.
4. Use Run now to test immediate execution path.
5. Verify working directory exists.
6. If runs stay behind, check diagnostics for scheduler.tick.backlog_capped (oldest pending entries are dropped when per-task backlog reaches AGENT_SPACE_SCHEDULER_PENDING_BACKLOG_LIMIT, default 240).

Scheduled Action Fails Immediately

1. Check Last error on schedule card.
2. Verify prompt is non-empty and scoped.
3. Verify runtime dependencies for your command/tooling.
4. Tighten prompt and retry manually.

Duplicate Scheduled Run After Restart

1. Check diagnostics for scheduler.ledger.pruned.
2. Verify AGENT_SPACE_SCHEDULER_MINUTE_LEDGER_RETENTION_MINUTES is not set too low.
3. Confirm ~/.agent-observer/scheduler-minute-ledger.json is writable.

Todo Runner Job Not Progressing

1. Verify Runner command exists and is executable.
2. Run the same command manually in target directory.
3. Confirm runner reads env/stdin payload.
4. Confirm runner exits non-zero on failures.
5. Check job card for the current failed todo and retry count.

Todo Runner Item Keeps Failing

1. Capture stderr/error from runner output.
2. Reproduce the item manually outside Todo Runner.
3. Fix dependency or prompt issue.
4. Check the job card's Next retry timestamp to confirm backoff cadence.
5. Click Start to continue from remaining items.

If attempts reached max and item is blocked:

• fix root cause
• use Reset Progress only if full replay is acceptable

Duplicate Active Agents

If one chat appears as multiple office agents:

1. Refresh session state.
2. Restart app.
3. Reopen one chat and confirm single active thread.

Install Count Not Increasing In Production Mode

1. Confirm desktop Settings -> Diagnostics -> Anonymous install beacon is enabled.
2. Confirm backend has AGENT_OBSERVER_WORLD_INSTALL_SOURCE=production.
3. Confirm ingest endpoint is reachable (POST /api/install-beacon).
4. Confirm rate limits are not being hit (429 with Retry-After).
5. Confirm backend aggregate store path is configured as expected (AGENT_OBSERVER_INSTALL_BEACON_STORE_FILE).

If beacon opt-out is enabled, this installation will not contribute to production install count.

If You Need A Clean Baseline

1. Close extra tabs/runs.
2. Reopen one workspace.
3. Test one small prompt or one short todo item.
4. Add complexity incrementally.