Troubleshooting
Cial rewrites its own front-end, which introduces a failure mode no ordinary app has: a change can compile cleanly and still break at runtime — a blank page, a stuck spinner, an error where the interface should be. The client-recovery subsystem exists for exactly this, under one rule: the way out must never depend on the thing that broke. The rest is the handful of issues that actually recur.
Client recovery
A failed compile is the easy case — Cial never swaps in a build that doesn't compile, so the working app keeps serving. The hard case is a build that passes compilation but fails when your browser runs it. Three independent layers, none of which depend on the SPA bundle, handle it:
Versioned builds. Cial never overwrites the live front-end in place. Each build lands in its own versioned directory; a single pointer names which one is served. Swapping versions only moves that pointer — no rebuild, no copy — so rollback is instant and a half-finished build can never corrupt the running version. A small pool of recent builds is kept as rollback targets (the newest known-good one is protected from cleanup) on the instance's own disk, so it survives a code reset. Because the swap is atomic, a client-only change goes live with no server restart; a restart is only needed when the change touches server code.
Boot watchdog. A tiny script in the page's HTML — not the application bundle — so it runs even when the bundle is broken. It routes you to the recovery page on any of three runtime failures:
- a bundle script that fails to load (404 or network error),
- a runtime error before the app mounts (uncaught exception), or
- the app never mounting within ~12 seconds (the white-screen backstop).
When the real interface renders, it pings the watchdog to stand down and reports the boot to the server, promoting that version to known-good. "Known-good" is strict: a build earns it only by booting in a real browser, never by merely compiling — so a build that crashes on load can never become a rollback target.
Recovery page. Rendered by the server as inline HTML, served from no build — so it loads no matter how broken the front-end is. You'll recognize the Cial bubble and a list of recent builds (date, time, short version id); hover a row for a Roll back button. Access is gated to you, the account owner: when the SPA has white-screened but your browser is still signed in, the edge admits you with a verified, machine-bound assertion that a different tenant can't produce — which is why the address and sign-in state below matter. See signed request proofs and the edge tier.
When the screen goes blank
You don't trigger recovery — the watchdog does. Getting back is one click:
- Wait for the recovery page. A blank or stuck app routes you there automatically (Cial bubble + version list).
- Pick a version. Hover a row for Roll back. The most recent known-good build is safest — the watchdog already confirmed it in a real browser.
- Click Roll back. Cial swaps the live pointer to that build immediately — no rebuild. The working app returns at once.
Rollback only moves the pointer between builds already on disk, so it's instant and reversible. Sessions, settings, and data are untouched — only the front-end assets swap. Landed on the wrong version? Roll back again.
Can't reach the recovery page? Refresh, and confirm you're at your usual workspace subdomain and signed in. The page is owner-only and authenticates through the edge, so the wrong address or a signed-out session keeps you out.
Once you're back in, pick up where you left off. If the change you asked for is what broke things, just say so in a chat — "the last change broke the app, please undo it" — and let Cial work out the steps. See Customize for how changes are applied and undone.
Common questions
A turn looks stuck or frozen. After a long stretch in the background, this is almost always a dropped live connection, not a stuck agent. Refreshing reconnects the WebSocket and resyncs the session, pulling the conversation — including any turn that ran while you were away — up to date. Prefer a ping when a turn finishes? Enable notifications (see Collaboration).
I'm not getting notifications. Push is enabled per device by design — each device registers its own service worker and subscription, so enabling it on one doesn't enable it elsewhere. Open Settings → Notifications on the device that's missing alerts and check the toggle. On iPhone/iPad, add the app to your Home Screen first — Web Push only works from an installed PWA. See Collaboration.
A change disappeared after a restart. A front-end change goes live the moment it's built but only persists across restarts once committed. If one is gone, ask the agent to make it again and save it. See Customize.
A feature I expected is missing. Many surfaces sit behind a per-user visibility layer: a feature registry resolves what each person sees and gates each surface. Toggleable features live under Settings → Discovery — so a surface that isn't where you expect may simply be off for you. See Customize.
A connected account stopped working. If sessions fail or you see engine errors, the credential for your connected account likely needs refreshing — the resolved credential is injected into each turn's environment, and an expired one fails the turn. Reconnect under Settings → Harnesses. See Customize.
Something else. Describe what you're seeing and what you expected in a chat — Cial can look into it directly.