Observability and recovery
Operate iPolloWork with explicit health signals, scoped logs, release evidence, and a recovery path that preserves workspace ownership.
Good operations do not start with a dashboard. They start by separating what is actually unhealthy: the desktop application, iPolloWork Server, the OpenCode sidecar, a specific workspace, an optional control-plane resource, or an external connector. The evidence and recovery owner are different for each layer.
A green process is not enough. The signal must answer whether the user path, configured workspace, and required capability are available.
What a person can use
The visible UI can open the intended workspace and show a real task state.
A small actual action completes through the target surface.
What executes local work
Prove reachability and resolved runtime state.
Prove the needed feature and workspace-specific activity are available.
What runs agent work
Checks iPolloWork Server and OpenCode as a paired system.
A stable run ID relates host and sidecar evidence without exposing credentials.
What adds shared organization capability
Workers, connector events, grants, and provider state are re-read by ID.
Privileged organization actions are assessed through the control-plane record, not local logs alone.
Health is a layered probe, not one boolean
| Question | First signal | Follow-up signal |
|---|---|---|
| Can clients reach the local runtime? | GET /health | GET /status and GET /capabilities |
| Can this caller access the workspace? | GET /whoami and GET /workspaces | the workspace-specific config or event route |
| Can agent work run? | ipollowork status | one small end-to-end task through the actual client path |
| Did a remote operation finish? | resource ID returned by the request | current Worker, connector target, discovery, or sync-event representation |
| Is an import or file action visible? | explicit artifact or file-session read | event/catalog read-back after the intended operation |
For a self-hosted runtime, do not publish only an HTTP reachability check. A deployment is useful only when a correctly scoped caller can reach the configured workspace and use the required capability.
Correlate without leaking secrets
The orchestrator can emit a unified log stream from OpenCode and iPolloWork Server. Use JSON output when logs enter a system that indexes structured fields:
IPOLLOWORK_LOG_FORMAT=json \
ipollowork start --workspace /path/to/workspace --run-id release-2026-07-15
The local server logs request method, path, status, and duration. OpenCode's log level can be passed through --opencode-log-level <DEBUG|INFO|WARN|ERROR> when the host starts it. Do not add client tokens, host tokens, provider keys, or raw pairing credentials to a run ID, shell history, copied logs, or support tickets.
Every recovery should finish with the smallest real task that originally failed.
- 01Capture
Record the exact user path, workspace ID, request time, status signal, and a redacted run correlation value.
- 02Classify
Identify the owning boundary: UI, local server, sidecar, workspace configuration, control plane, or external connector.
- 03Repair narrowly
Change the failing owner only—configuration, sidecar source, expired credential, or remote resource state.
- 04Re-prove
Repeat the original path and re-read the health, status, event, artifact, or resource state that proves success.
Release gate: prove more than compilation
Use a staged release gate. The exact commands vary by delivery target, but the evidence must remain comparable:
- Static correctness — run the package's narrow type, test, or build check for the changed boundary.
- Artifact correctness — use
package:dirwhen an unpacked Electron app is enough to validate the desktop flow; reserve a native package for installer verification. - Runtime correctness — start the actual local server or orchestrator path and check health plus capabilities.
- User-path correctness — complete one focused task in the UI or remote client that uses the changed feature.
- Rollback readiness — know the previous artifact, configuration version, and owner responsible before changing a remote deployment.
The repository's ./ipollowork check is a verification command, not a deployment mechanism. package:dir creates a local validation artifact; package creates host-native installers. Neither command by itself pushes a release, changes GitHub tags, or updates a hosted control plane.
Recovery playbooks
The server is reachable but a workspace cannot be used
Read GET /whoami, GET /workspaces, then the target workspace config and events. Check that the workspace declaration, token scope, approval posture, and CORS origin match the client actually in use. Restart only the owning server process after preserving the error and resolved configuration evidence.
The sidecar fails after a host change
Use ipollowork status, enable --verbose, and confirm the resolved sidecar policy before changing anything else. A downloaded, bundled, and explicitly external binary are different release inputs. Fix that source selection first, then rerun a small end-to-end task.
An asynchronous Cloud operation appears stuck
Use the returned resource ID to read the Worker, connector target, discovery, or sync event. Do not create a duplicate account or Worker because the original request was only accepted. Retry the specific retryable resource only after its current state is understood.
A destructive or permission-sensitive request is pending
Review it through the approval or owner flow. Do not bypass manual approval with a production-wide auto setting. If access is incorrect, repair the token or grant boundary, then repeat the request with the smallest appropriate scope.
For exact runtime construction continue with Orchestrator and sandbox. For private network and server configuration continue with Self-hosted topology.