App Control & Recovery

What it is

Most of Omniscio's controls act on your sessions and projects. App Control acts on Omniscio. When the interface looks frozen or blank, when the app is rendering oddly because it fell back to software drawing, or when you are running from source and your code changes have not taken effect, these are the levers that put the app itself right again.

It also covers the safety net around the app's data: the list of backup restore points, and the two paths that put an older or mirrored copy of the database back. Those restore operations are destructive by nature - they replace what is there now - so they are approval-gated and never run silently.

Where to find it

These controls surface through the local control server and the app's own recovery affordances; a user reaches them by asking an agent, or from the settings and recovery areas that expose the same actions. The user-data path read tells you where Omniscio keeps its database and configuration if you need to look yourself. The backup list shows the restore points available to roll back to.

How it behaves

The everyday recovery moves are quick and safe. A reload is a hard refresh of the interface - cache cleared, page reloaded - which fixes the stale or frozen cases without touching your work; because it interrupts whatever the user is looking at, it is locked to the full-trust token, so a scoped agent token cannot fire it. On a development install, a restart quits the app gracefully and relaunches it, so it picks up code changes including the mobile bundle. If Omniscio switched itself to software rendering, resetting that flag and relaunching gives hardware acceleration another try. When you run from source and the checkout has fallen behind, a safe catch-up brings it up to date and backs your work up first; on a packaged install, where there is no source to catch up, it declines rather than guessing.

Restarting is the one everyday action with a two-part gate, because a restart is visible from the user's chair. The owner has a switch - off by default - that decides whether full-trust callers such as scripts, crons and the dev supervisor may restart at all; while it is off every such caller gets a refusal, which the supervisor treats as a deliberate no-op rather than escalating to a hard kill. A spawned session cannot use that switch: it is admitted only by a per-session permission the owner grants it, and it asks for one by queueing an approval card. No caller can grant itself either. Outside npm run dev there is no supervisor to relaunch the app, so the route refuses instead of half-quitting. A restart is never anonymous: the app records who asked, and the relaunch raises an inbox notice naming them.

The backup path is where care is needed. Listing backups is a read. Restoring from a backup, or merging in a mirror archive, replaces the live database and is destructive, so both are approval-gated: they wait for your explicit sign-off before running.

For agents

• Reads: GET /app/user-data-path (the resolved user-data directory where the DB and config live), GET /backup (list restore points), GET /gpu/auto-disable-state (the gpuAutoDisabled cookie).
• Safe actions: POST /app/reload (hard-reload the renderer; full-trust token only), POST /app/restart (dev-only graceful quit + fresh relaunch), POST /gpu/reset-and-relaunch (clear GPU auto-disable and relaunch), POST /sync-drift/safe-recover (safe catch-up of a run-from-source checkout, backing work up first; 409 on a packaged install).
• POST /app/restart gating, in full: full-trust callers are governed by the owner switch allowAgentAppRestart (default off — a 403 disabled for every one of them); a spawned session's own scoped token is admitted only by a per-session grant, and asks for one via POST /app/restart/permission-request, which only queues a card a human must approve. Outside npm run dev it is a 409. A cli-token caller must identify itself (source session, active cron, or the dev supervisor's origin header); the restart is recorded and the relaunch raises a "was restarted by <who>" notice.
• Destructive, approval-gated: POST /backup/:id/restore (restore the live DB from a backup) and POST /backup-mirror/restore (restore/merge a mirror archive). Never invoke these on your own initiative.
• Anchors: src/main/services/cli/cli-server-app-reload-routes.ts, src/main/services/cli-server-app-restart-routes.ts, src/main/services/cli/cli-server-gpu-routes.ts, src/main/services/cli/cli-server-sync-drift-routes.ts, src/main/services/cli/cli-server-backup-routes.ts.

Related

• cli-control.md — the broader CLI control surface App Control belongs to
• cost-control.md — the spend-side controls that sit beside these
• cli-pending-actions.md — where approval-gated actions wait for sign-off
• mission-control-part-2.md — the control hub these switches are wired through