# Troubleshooting and shortcuts

>  © 2026 Quadropic Pvt Ltd. Proprietary and confidential. [Use restrictions](NOTICE.md).

## Fast diagnosis

| Symptom | First check | Likely next step |
|---|---|---|
| Send redirects to Settings | Selected preset has no usable model | Configure provider, model, and authentication |
| Agent cannot find a file | Wrong workspace or overly broad request | Select the correct directory and `@` mention the file |
| Code Atlas describes old code | Index is stale for the current checkout | Sync the workspace index |
| Agent appears frozen | Approval or structured question is pending | Open the task and respond |
| Request is too large | Thread context is near/full | Compress context or start a clean thread |
| Changes are in an unexpected directory | Thread is in a Virtual Edit or room worktree | Check effective directory in Terminal/Open |
| File Diff is empty/incomplete | Changes were external or not captured as edit results | Use `git status` and `git diff` |
| Conductor created cards but nothing runs | Creation and start are separate operations | Tell Conductor to start every intended task |
| Schedule did not fire | App was closed/asleep, schedule disabled, or timezone differs | Run now, verify status/timezone, keep app open |
| MCP tool is missing | Server disabled, stale catalog, or User invoked | Refresh server or mention the tool with `@` |
| Phone cannot pair | Network/address/code or relay state is wrong | Rotate code, try manual details, verify WSS relay |

## Model and provider problems

### “No provider configured” or send opens AI Provider

1. Open **Settings → AI Provider**.
2. Find the lane used by the selected preset/action.
3. Choose an available provider and model.
4. Save an API key or complete OAuth.
5. If using Ask from Standard, also verify Light.
6. If using Architect or Debug from Standard, verify Hunter.

If a model is labeled **unavailable**, its saved ID is no longer present in the provider catalog. Select a current model or restore the custom endpoint.

### Authentication fails

- Confirm the credential belongs to the selected provider.
- Check whether the lane is configured for Key or OAuth.
- For an existing Claude subscription use Anthropic OAuth; for ChatGPT Plus/Pro use OpenAI Codex OAuth, not the regular OpenAI key provider.
- For OAuth, retry Authenticate or refresh the token.
- For a custom endpoint, verify base URL, API dialect, and optional key environment variable.
- Do not paste secrets into the chat for diagnosis.

### Context meter is clearly wrong

For custom models, correct the configured context window. For catalog models, switch away and back after provider metadata refresh. Treat the lower known limit as authoritative until verified.

## Workspace and file problems

### The agent edits the wrong project

Stop the run immediately with `⌘Esc` / `Ctrl+Esc`.

Then:

1. Inspect the task’s workspace label.
2. Check whether it inherited a room worktree or owns a Virtual Edit.
3. Run `pwd` and `git status --short --branch` in the task Terminal.
4. Preserve and classify any edits before changing directories.
5. Start a new thread in the correct workspace if the boundary was wrong.

Do not “clean up” with a destructive Git reset.

### A file does not appear in `@` search

- Confirm the composer’s selected workspace.
- Type more of the relative path.
- Check whether the file is ignored, generated, or outside the workspace.
- Add the correct directory as a separate workspace if it is legitimately out of scope.

### Search results are irrelevant

Use concrete symbols and domain nouns. Replace:

```text
How does this work?
```

with:

```text
Trace checkout session renewal and account-state persistence.
```

Mention the nearest known file and ask the agent to trace outward.

## Run, approval, and context problems

### The agent is waiting

Look for:

- the hand/attention indicator in the sidebar;
- a tool approval card;
- a structured question;
- a pending request in a sub-agent tool card;
- system-tray “needs input.”

If several approvals are pending, use left/right arrows to navigate the approval dock.

### An approval is no longer pending

The run may have stopped, timed out, or already handled the request. Refresh/open the task and inspect its latest status. Do not repeat a side-effecting command until you know whether the first call executed.

### The run is stuck in a bad direction

Send one steering delta. If it does not correct course, stop and restart with:

- the same observable outcome;
- corrected evidence;
- discarded hypothesis;
- explicit next inspection target.

Do not stack several contradictory steering messages.

### “Request too large” or context over 90%

If the objective is unchanged, compress using `⌘⌥C` / `Ctrl+Alt+C`, then restate authoritative constraints. If the objective changed, start a new thread.

If compression fails:

- remove unnecessary draft images;
- start a new thread;
- mention durable files/plans instead of pasting old history;
- use a model lane with a verified larger context window only when the additional context is actually useful.

### A run stopped

Read the run card:

- **stopped** means a user/system stop was processed;
- **failed** includes the provider, tool, or runtime error;
- an Autonomy task may show interrupted/paused and can be resumed.

Before retrying a side-effecting task, inspect current files and external state. A failed final response does not prove that earlier tool calls were rolled back.

## Git and diff problems

### File Diff shows no changes

The panel reflects captured edit artifacts, not the full repository truth. Run:

```bash
git status --short --branch
git diff
git diff --cached
```

Generated files, external editor changes, or commands that rewrite files may not have a line-level widget.

### Virtual Edit cannot be created

Check:

- the workspace is a valid Git repository;
- there is a selected workspace;
- Git can create a worktree and branch;
- the managed worktree location is writable;
- a stale worktree entry is not blocking the branch.

Ask the agent to inspect `git worktree list` before changing any worktree metadata.

### Apply Layer fails

The base branch and layer may conflict or the base working tree may be dirty. Preserve both states, inspect the error, and choose a deliberate integration strategy. Do not delete the layer until its unique changes are backed up or integrated.

### Commit contains the wrong files

`Add Current Changes` stages everything. Before committing:

```bash
git diff --cached --name-status
git diff --cached
```

If the commit has not been shared, choose a correction consistent with your Git policy. If it has been pushed/shared, prefer a follow-up commit unless history rewriting is explicitly authorized.

### Pull or Sync refuses

Pull uses `--ff-only`, so divergence is intentional failure. Fetch and inspect:

```bash
git status --short --branch
git fetch --all --prune
git log --oneline --decorate --graph --max-count=30 --all
```

Then decide whether to rebase, merge, or keep branches separate.

## Autonomy and Conductor problems

### Task card exists but no agent is running

Creating a manager task only stages a card. Open its menu and choose Run, or tell Conductor:

```text
Start every task you created for this objective and verify each is In Progress.
```

### Two agents collide

Stop at least one writer. Assign exclusive files or subsystems, nominate an integration owner, and communicate current worktree state. In a shared room worktree, changes are immediately visible; “different task” does not mean “different filesystem.”

### A room agent cannot see another agent’s changes

Check its worktree mode:

- Inherit sees the room worktree;
- Detached uses the base workspace;
- Child uses its own worktree.

Move or recreate the task with the intended mode. Do not copy changes manually before identifying the source branch/worktree.

### Room history is cluttered

Archive completed agents, remove abandoned idle tasks, and keep General Hall for triage. Use named rooms for durable initiatives and delete rooms only after handling their worktrees and artifacts.

## Marketplace problems

### Skill does not influence the task

- Confirm it is enabled.
- If User invoked, add it with `@` in the same turn.
- Verify you selected the intended Skill when a source contains several packages.
- Read its trigger and ensure the request matches.

### MCP tools are not discovered

1. Confirm the server is enabled.
2. Use Refresh MCP tools.
3. Read the displayed refresh error.
4. For stdio, verify command, arguments, environment, and executable availability.
5. For HTTP/SSE, verify URL, TLS, authentication, and network.
6. If User invoked, mention the exact tool with `@`.
7. Refresh **Settings → Permissions** after discovery.

### MCP call is denied or repeatedly asks

The tool’s current permission is Ask. Approve once/turn, or set the individual tool to Allow after evaluating its full capability. If it does not appear in Permissions, refresh both Marketplace and Permissions.

## Schedule and mobile problems

### Schedule is overdue or missing

- Syntheo must be open.
- The machine must be awake.
- The schedule must be enabled.
- The stored timezone and cron must match your intent.
- The target directories must still exist.
- Required provider credentials and permissions must be available.

Use **Run now** and inspect the resulting task before changing the cron.

### Schedule repeatedly creates unwanted changes

Disable it first. Inspect every run’s workspace and Git state, then make the prompt idempotent and add explicit no-commit/no-push boundaries. Test manually before re-enabling.

### Local phone pairing fails

- Put phone and desktop on the same reachable network.
- Rotate to a New code.
- Use the manual address and code.
- Check local firewall/VPN isolation.
- Keep the Mobile Companion settings page open while pairing.

### Remote companion fails

- Require a `wss://` public URL.
- Check relay status and error.
- Confirm the desktop has outbound network access.
- Confirm the phone can reach the relay.
- Turn the relay off and back on only after recording the error.
- Remember that remote access requires the desktop and Syntheo to remain online.

## Keyboard shortcuts

`⌘` means Command on macOS. On Windows/Linux use Control unless the row specifies otherwise.

### Navigation and surfaces

| Action | macOS | Windows/Linux |
|---|---|---|
| New thread | `⌘N` | `Ctrl+N` |
| Add/open workspace | `⌘O` | `Ctrl+O` |
| Toggle sidebar | `⌘B` | `Ctrl+B` |
| Settings | `⌘,` | `Ctrl+,` |
| Autonomy view | `⌘⇧A` | `Ctrl+Shift+A` |
| Conductor (from Autonomy) | `⌘⇧C` | `Ctrl+Shift+C` |
| Open workspace in preferred app | `⌘P` | `Ctrl+P` |
| Terminal panel | `Ctrl+\`` | `Ctrl+\`` |
| Browser panel | `⌘⇧B` | `Ctrl+Shift+B` |
| File Diff panel | `⌘⇧D` | `Ctrl+Shift+D` |
| Git menu | `⌘⇧G` | `Ctrl+Shift+G` |
| Privacy Veil | `⌘⇧V` | `Ctrl+Shift+V` |

### Composer and task

| Action | macOS | Windows/Linux |
|---|---|---|
| Focus composer | `⌘K` | `Ctrl+K` |
| Submit | `Enter` | `Enter` |
| New line | `Shift+Enter` | `Shift+Enter` |
| Cycle Architect / Ask / Debug | `Shift+Tab` | `Shift+Tab` |
| Run selected secondary action | `⌘⇧Enter` | `Ctrl+Shift+Enter` |
| Model preset menu | `⌘⇧M` | `Ctrl+Shift+M` |
| Add image | `⌘⇧I` | `Ctrl+Shift+I` |
| Queue Virtual Edit for next thread | `⌘⇧E` | `Ctrl+Shift+E` |
| Compress context | `⌘⌥C` | `Ctrl+Alt+C` |
| Stop active agent | `⌘Esc` | `Ctrl+Esc` |

### Mentions, approvals, and dialogs

| Context | Keys |
|---|---|
| Move in `@` results | `↑` / `↓` |
| Select mention | `Enter` or `Tab` |
| Close mention/menu/dialog | `Esc` |
| Previous/next pending approval | `←` / `→` or `<` / `>` |
| Allow selected approval once | `⌘Y`, `Ctrl+Y`, or command/control + `Enter` |
| Deny selected approval | `⌘N` / `Ctrl+N` |
| Navigate multiple images | `←` / `→` |
| Image zoom in/out/reset | `⌘+` / `⌘-` / `⌘0` (Control equivalents on Windows/Linux) |

Global shortcuts can be owned by the application menu. If another application or operating-system shortcut intercepts one, use the visible top-bar control.