TroubleshootingTasks and runtime

Tasks and runtime

Diagnose waiting, stuck, interrupted, failed, or inconsistent Synara tasks without losing the working state.

Troubleshooting

A task can be blocked on user action, actively working, interrupted, idle, or in an error state. Read the task state before deciding that the provider is stuck.

Understand the task status

StatusMeaningFirst action
workingThe provider session or latest turn is starting or runningInspect recent activity and wait for evidence of progress
waiting-for-approvalA tool or action requires approvalRead the request and approve or reject deliberately
waiting-for-user-inputThe provider asked a questionAnswer precisely or interrupt the turn
interruptedThe latest turn was stoppedInspect partial changes before retrying
errorThe session or latest turn failedPreserve evidence and read the exact failure
idleNo turn is currently runningReview the result or send a new instruction

Pending approvals and user-input requests take precedence over a generic running state. A task blocked on a gate is not making progress until that gate is handled.

Task appears stuck

Do not begin by repeatedly sending follow-ups.

  1. Check for an approval or user-input request.
  2. Inspect the latest transcript activity and terminal output.
  3. Check whether the provider process is still present and producing events.
  4. Inspect the diff for partial work.
  5. Wait long enough for the specific operation; installs, builds, and large repository scans can be slow.
  6. Interrupt only when there is no useful progress or the work is unsafe.
  7. Preserve the current state before starting another provider session.

A quiet transcript is not by itself proof of a dead process. Use Diagnostics when the visible state and runtime behavior disagree.

Task is waiting for approval

Read the requested command or operation in full.

Before approving, verify:

  • The task is operating in the expected project and environment
  • The command matches the objective
  • The path is inside the intended worktree or checkout
  • The action does not expose secrets or mutate unrelated systems
  • The provider is not following untrusted instructions from issue text, web content, or repository files

Reject or interrupt when the action is broader than necessary. Approval is authorization, not confirmation that the action is correct.

Task is waiting for user input

Answer the actual question rather than restating the whole objective.

Good response:

Use the existing retry helper. Do not change the public API. Run only the focused queue tests first.

When the question reveals a wrong assumption, correct the assumption before allowing the provider to continue.

Recover expired questions

Pending Claude questions and draft answers can be restored after navigation or restart. If the provider session has expired, Synara shows an expired-question notice instead of submitting answers to a dead request. Choose Restore answers to put the saved answers into the composer, review them, then send them as a new message. Dismiss removes that recovery draft. Restoring alone does not send anything.

Session restart and context loss

Transcript rail indicators distinguish a provider session restart from context loss or compaction. The task and checkout can remain intact while provider-native context changes. Inspect the indicator and the latest instruction before continuing; scrolling to earlier messages does not restore a lost native session.

Turn was interrupted

An interrupted turn may have already changed files or started commands.

  1. Inspect git status --short.
  2. Read the diff and untracked files.
  3. Check whether child processes are still running.
  4. Preserve useful work.
  5. Decide whether to continue the same task, hand it off, or create a clean task.

Do not assume interruption rolled back filesystem changes.

Provider reports completion but the task is not complete

The final provider message is a report, not proof.

Verify:

  • The original objective is satisfied
  • Every changed file is understood
  • Focused tests pass
  • Broader checks pass when shared behavior changed
  • Visible behavior was tested when applicable
  • No unrelated files or generated artifacts remain
  • The final Git head is the head you tested

Continue with Best practices for the full verification model.

Session failed to resume

Provider-native session identifiers, resume rules, and context formats differ.

Try this sequence:

  1. Preserve the working tree.
  2. Record the provider, model, task ID, and last successful turn.
  3. Retry resume once after confirming the provider is healthy.
  4. Start a new provider session in the same task when Synara supports that recovery path.
  5. Use a provider handoff when another provider should continue the same environment.
  6. Create a new task only when you want a new ownership and review boundary.

A new provider session may preserve the Synara task and working environment without preserving every provider-native internal state.

Repeated runtime errors

When the same error repeats:

  • Stop automatic retries
  • Capture the first and latest exact error
  • Record whether any filesystem or remote effect committed
  • Compare a new minimal task in the same repository
  • Compare a disposable repository with the same provider
  • Update the provider only after recording the failing version
  • Remove one optional extension, hook, MCP server, or custom option at a time

This separates a repository-specific failure from a provider-wide or Synara-wide failure.

Journal or event-delivery warnings

Synara persists orchestration state and provider runtime events. A warning about a journal, delivery, or quarantined provider event should be treated as an operational failure, not dismissed as cosmetic.

  1. Stop adding new work to the affected task.
  2. Preserve the working tree and final visible response.
  3. Record the exact warning and time.
  4. Use synara_diagnose_thread when an authorized Agent Gateway session is available.
  5. Inspect durable thread events and provider-runtime coverage.
  6. Start a new task only after the current work is safely preserved.

Do not claim that an event was absent unless the diagnostic source reports complete coverage.

Two tasks touched the same checkout

Stop both writers.

  1. Record each task and provider.
  2. Inspect the checkout diff and Git status.
  3. Identify which task owns each intended change.
  4. Preserve the combined state before reverting anything.
  5. Move future work into separate worktrees.
  6. Assign one integration owner to resolve the current diff.

Do not ask both providers to “fix the conflict” in the same checkout.

Runtime recovery checklist

  • The current task status was identified
  • Pending approvals or input were handled explicitly
  • Partial filesystem changes were inspected
  • Child processes were checked after interruption
  • The exact error and time were recorded
  • Diagnostic coverage was considered before claiming an event was missing
  • Only one task owns the recovery
  • The final result will be independently verified

Review interrupted or waiting work

Synara 1.0.1 preserves failed-turn feedback after session recovery. Open the thread error details and copy them when reporting a failure. Answered questions remain visible in the transcript, and Enter submits asynchronous answers. Stale provider questions settle instead of leaving the chat waiting indefinitely.

Reconnect notices explain real transport reconnects. In 1.0.6 the misleading server-busy popup and client heartbeat were removed; local health and event-loop status remain available. A resumed session or a finished turn alone does not establish that requested work succeeded; inspect the resulting files and runtime behavior.

Missing owner during restart recovery

In 1.0.3, recovery isolates persisted child commands when their owning task is missing or deleted. Synara does not create a replacement provider session or resend that abandoned work. Unsent commands are blocked, ambiguous delivery remains uncertain, and a surviving child reports an error while unrelated tasks remain usable.

Claude compaction reviews with an unavailable owner stay held for reconciliation. Preserve their messages and inspect the error rather than repeatedly retrying. Chat deletion cancels queued work before optional computer cleanup; a cleanup failure or timeout cannot leave promotions stuck.

The desktop also initializes a maintained HTTP dispatcher before requests to avoid Electron 43's macOS socket crash. This does not establish live provider success; use the task's actual connection and turn state.

Source evidence: Synara v1.0.3 apps/server/src/orchestration/Layers/ProviderCommandReactor.ts, docs/providers.md and apps/desktop/src/httpRuntime.ts.

Unexpected shutdown recovery

Starting with 1.0.4, Synara can automatically continue an ordinary human chat that was actively running when the server stopped unexpectedly. It uses the saved conversation and provider selection and asks the agent to inspect existing operations before repeating them. This is a continuation, not automatic replay of an in-flight tool call.

Chats waiting for approval or an answer, still starting, archived, or owned by native subagents, delegated tasks, goals, Hubs or scheduled automations are excluded. Their existing recovery paths or manual controls still apply. Explicit choices made when quitting take precedence over this fallback.

After reopening, inspect the continuation and the workspace before assuming a previous operation failed. Active-session cleanup also rechecks live work before stopping a provider; delayed Codex terminal notifications cannot finish a newer turn.

Workspace file requests stop responding

In 1.0.4, opening a POSIX named pipe (FIFO) through workspace file reads or version-checked saves is rejected without blocking a filesystem worker. This fixes a reproduced starvation case on macOS/Linux. A regular text file remains a useful control when investigating file-request failures.

This does not diagnose every slow or unresponsive request. If the issue continues, record the requested path type, exact error, current task state and whether an unrelated regular-file read works. Preserve the workspace rather than resetting the database.

Source evidence: Synara v1.0.4 (a62d7c733d19f5538ffc0d126d57437b3b578ff1) apps/server/src/orchestration/quitResume.ts, apps/server/src/effectServer.ts, apps/server/src/provider/Layers/ProviderService.ts, apps/server/src/codexAppServerManager.ts and apps/server/src/workspace/Layers/WorkspaceFileSystem.ts.

Long conversations and parallel work in 1.0.6

Long chats avoid repeated history scans and full-detail reads during routine turn updates. Parallel live streams suppress redundant replay polls and share bounded repository refreshes, retaining a final refresh after activity stops. Requests wait in bounded client queues before using server capacity. A capacity error can still occur; inspect mutation results before retrying uncertain work.

Runtime reconciliation preserves live turn ownership and pages through older candidates. Provider handoffs settle known outcomes without replaying native stop/start operations. These changes preserve saved history and do not justify resetting the database.

Source evidence: Synara 1.0.6 ProjectionSnapshotQuery.ts, ProviderCommandReactor.ts, ProviderRuntimeReconciler.ts, wsTransport.ts and docs/event-loop-stalls.md.

Long-running turns and live changes in 1.0.7

Streaming answers reuse settled Markdown blocks, and ordinary updates avoid refreshing every transcript row. Server usage reads reuse unchanged transcript files and parse appended records. Full conversation history remains available.

During file-edit bursts, live files-changed captures run at most about every three seconds per thread, with a final trailing capture. A briefly unchanged count is not evidence that the agent stopped editing. Read-only tools avoid unnecessary Git refreshes. PR status refreshes at turn end, branch changes, focus and regular polls.

Windows prepares a bounded process observer before starting an owned OpenCode runtime and retains it through runtime pool reuse. Teardown reads fresh evidence and still requires process identity and exit proof. A timeout or cleanup error is not success; preserve its exact error and inspect surviving processes.

For a message edit that restored an earlier workspace, inspect the retained recovery snapshot before attempting further rollback.

Source evidence: Synara v1.0.7 (b8cf9382d36ac1120b3fe16241cfd96189a9a71e); apps/server/src/orchestration/Layers/CheckpointReactor.ts, apps/server/src/providerUsageSnapshot.ts, apps/server/src/provider/opencodeRuntime.ts, apps/server/src/platform/windowsProcessSnapshot.ts and apps/web/src/components/ChatMarkdown.tsx.

Storage maintenance in 1.0.8

Deleting chats makes SQLite pages reusable; the file may remain larger than its live data. New databases reclaim free pages incrementally. Existing databases may attempt a one-time rebuild after clean shutdown only with enough free pages and scratch space. Insufficient space or a bounded timeout defers maintenance. This does not delete additional chat content and is not an emergency disk-recovery guarantee. Do not remove the database or its WAL to force reclamation.

Stopped Pi and Antigravity sessions become inactive for ordinary next-turn recovery. An unanswered foreground Computer Use prompt is cancelled; it is not recorded as a human decline. Preserve the actual error and task state before retrying.

Stop retries and durable progress in 1.0.9

Conditional Stop saves its original runtime and turn before sending physical control. A retry finishes that same target and cannot stop a replacement runtime or a later turn. If the target cannot be saved, no provider stop is sent. Failed observations remain retryable or explicitly uncertain; inspect the reported outcome before assuming work stopped. Interrupt-only controls preserve queued messages and transcript context.

Command progress keeps its identity across recovery and replay. Provider errors show a readable first-line message; retain logs when deeper diagnostics are needed.

Compressed migration backups in 1.0.9

New pre-migration SQLite backups end in .sqlite.gz. Recovery and inspection accept these compressed snapshots and older .sqlite backups. Keep the backup, recovery marker and provenance together; do not manually replace the live database with the compressed file.

Creation needs temporary space for the full snapshot and compressed output together. Compression is not emergency disk recovery and has no guaranteed ratio. If the space check refuses startup, free space without deleting the recovery evidence, then retry. Synara retains at most five completed pre-migration backups.

If startup reports migration recovery is required, stop every Synara process and use the exact synara-restore-migration-backup command printed for that database. The tool validates and decompresses the marked snapshot before replacing the live database. Do not invent a backup path or restore while another instance owns the database.

Source evidence for 1.0.9: Synara release ebd0d22b39ce3a0f7c6051dddc6090e9b85dc7c3; docs/releases/1.0.9-source-audit.md, docs/providers.md, docs/core-concepts.md, docs/editor/intelligence.md, docs/mcp-connectors.md, apps/server/src/persistence/MigrationBackup.ts and docs/release.md.

Resume after usage limits in 1.1.0

Settings → Providers → Resume after usage limits defaults to off. Supported Codex and Claude tasks can wait for a verified account's future reset after a definitive terminal usage-limit refusal. Percentage warnings alone do not schedule work. Unknown, stale or ambiguous limits remain manual, and native provider retries retain their active turn.

The execution computer must be running; clients may disconnect. Pending waits survive a host restart but cannot wake a sleeping computer. The continuation checks saved work instead of replaying the failed prompt or tool call. Already accepted user messages have priority. Stop, a manual send, pause, archive/delete, goal changes, account/model/route changes or disabling the setting cancel the wait; re-enabling does not restore it.

Claude automatic recovery requires a verified native OAuth account profile on macOS or Linux. Windows, API-key/helper authentication, federation profiles and unreadable settings remain manual. Codex requires its native account ID. An uncertain delivery still needs reconciliation.

In 1.1.0, crash continuation, queued-message resumption and subagent recovery also preserve ownership more reliably. For a stalled Claude turn, Stop must establish runtime retirement; its dispatch acknowledgement alone is not cleanup proof. Unblock thread reconciles uncertain delivery and does not stop a live provider. Failed attachment preparation preserves drafts, and rejected native-review attachments do not discard work already accepted.

Source evidence for 1.1.0: application source d80787e3e4d8829a35a64b111e6fcbe5f51cf037; docs/releases/1.1.0-source-audit.md, docs/core-concepts.md, docs/providers.md, docs/internationalization.md and docs/sqlite-space-reclamation.md.

Automatic upgrade of the known Stable history in 1.5.1

Synara 1.5.1 recognizes the exact older Stable database history that could previously stop at the “Migration 136 does not match this build” confirmation. It saves a migration backup before replaying the missing migrations, then starts normally. Your saved threads and usage-recovery state are preserved. Each app retains its own data home.

A modified or unrecognized history still needs the existing review and confirmation. A failed backup or a database newer than the build still blocks unsafe startup. Keep the backup and recovery evidence; use the recovery command printed for that database if recovery is required. Do not delete or edit migration tracker rows to bypass a warning.

Source evidence for 1.5.1: Synara source 10f7801bfa141df4bab83f3238c65a534d8884fb; apps/server/src/persistence/Migrations.ts, MigrationBackup.ts, MigrationBackup.test.ts and docs/release.md.

Last updated on