App Control & Recovery
App Control is the set of switches for fixing Omniscio itself when the app, not a session, is the problem: reload a stale or frozen interface, clear a software-render fallback, and list or restore backups. Two of the controls below — restarting to pick up code changes, and catching a source checkout up — suit a from-source install only.
On this page
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.
A restart is announced to connected phones before the app quits, so they show "Omniscio is restarting on your computer — not down" instead of a connection warning, and on a development install they also show the rebuild step while the app is down (details).
A restart rebuilds the interface bundle behind its window when it safely can. In a development install the desktop window loads that compiled bundle by default (it is also what the phone is served), so a restart after a change that touched interface files used to spend about two and a half minutes rebuilding it while the app was down. A relaunch now starts that rebuild in the background and opens the window straight away — and since 2026-11-06 so does every ordinary start of a development install (the desktop shortcut or the sign-in autostart), which used to wait about three minutes for the same build on any day the code had moved. The rest of the app starts while the build runs; the windows hold their first load until it lands (at most five minutes) and then all load the fresh bundle, and a build that fails or runs past five minutes lets them load from the development server instead. The phone keeps the previous bundle until the new one lands. A rebuild caused by unsaved edits or by a changed language scope still runs in the foreground, because the app would otherwise boot on older interface than the code on disk. Only one rebuild runs at a time, its output and duration are logged in out/renderer-build-background.log and out/predev-chain.jsonl, and a first npm run dev or a folder that has never finished a launch keeps the old order. AMC_DISABLE_DEFERRED_MOBILE_BUNDLE=1 restores the old order everywhere; nothing needs setting to get the new one.
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 - and so does a development install whose supervisor has gone quiet: the app waits a short moment for that window to show it is still working, and refuses rather than quitting into a void with nothing left to bring it back. A launcher that is running but wedged reads exactly like one that has stopped, so the app watches what the launcher does rather than whether its process exists - if no sign of life arrives, the app stays up and the restart is declined. A restart is never anonymous: the app records who asked, and the relaunch raises an inbox notice naming them.
Before a dev restart goes ahead - from the Restart button, the menu, the inbox card or POST /app/restart - the app checks the folder it will launch for missing launch files and duplicate startup handler wiring. It compares the target migration filenames with the database's applied IDs and runs a schema-copy trial only when a migration is pending. The press-time check does not compile or boot the new code; the longer build checks remain separate. Its toast carries a Restart anyway button. A proven problem is shown with that same choice, and the route answers 409 naming the reason; an owner can press through with {"override":{"reason":"..."}}. If the check cannot get an answer, the restart goes ahead. The dev supervisor's own restarts skip it. Settings → Performance → Check for startup problems before a restart turns it off.
The press-time check above asks questions; the build itself is checked afterwards. When a dev restart has rebuilt the app and before it switches over to the new build, that freshly built main bundle is loaded once, in a throwaway child process. A bundle that crashes while loading - the failure that used to open an app that dies at boot, or leave the launcher silently serving an older build - is refused: the new build is never started, the banner in the terminal names the build and the one-line reason, the last good build is put back and opened, and one inbox card records it. A check that cannot reach an answer - too slow, or a machine too loaded to run it - never refuses; it says so plainly and the restart continues. It costs a few seconds on a rebuild (measured 3.2 seconds on the main bundle), and it runs only when a restart builds a new build: it is never part of a land and never part of the merge gate.
A restart makes the folder whole before it checks it. Two kinds of drift make a build impossible and each also stops the safety check itself from running, so the restart repairs both first: a tracked file that is missing from disk is restored from the last commit, and a path the last commit has but the folder's index has lost has its index entry restored - the file on disk is left exactly as it is. Measured 2026-11-06, a restart had been refusing to launch and falling back to the previous build in one second because the repair ran after the check that needed it, and later the same day because two committed database migrations had dropped out of the index and read as an unpublished file. A restart that is refused before the new build is even launched now says exactly that - that it stopped before launching - instead of reporting a build that stopped while starting up, which describes something that never happened.
A restart also waits for work that a quit would destroy. A dictation in flight is waited out, and so is a land train — the app's own merge train, which runs for five to fourteen minutes inside the app, so quitting mid-train threw the landing away and the next start marked it interrupted. When a train is running the route answers 200 with deferred.reason of land-train and restarts once the lane is idle, up to a twelve-minute cap; past the cap it restarts anyway and says so in the log. An AI code review that is still running is held the same way: the restart waits for the round to finish and answers 200 with deferred.reason of ai-review, and a restart that goes ahead anyway is recorded as having interrupted that round, so a review that never comes back is never a silent one. The same wait is re-checked immediately before every quit the route makes, including a train that starts during the startup check, so no ordinary road through the route can cut one. Three roads are exempt on purpose, because each is a person asking for a restart now rather than queueing one: the in-app Restart button, a second npm run dev started while the app is open (the dev supervisor's handoff), and an emergency restart (below). Each takes effect at once; a landing it cuts is marked interrupted at the next start.
Closing the window while a restart is still wanted is treated as that restart, not as quitting: the app records that a restart was asked for whenever one is accepted, deferred or stood down (the machine was in use), and a close within fifteen minutes of such a record relaunches instead of leaving the app down. It comes back once, with one informational inbox card explaining why; the next close quits for good. A deliberate full quit is untouched — quitting from the tray, Ctrl+Q, an operating-system shutdown, or any close with no restart pending ends the dev session and the app stays down.
When the app restarts itself in a dev install — re-enabling graphics acceleration, the Settings Restart now bar, recovering from repeated graphics crashes, the tray's Restart, a backup restore — the launcher now does that restart too, exactly as it does for the Restart button: it shows the same "restarting" step and a second npm run dev started meanwhile steps aside. Until 2026-10-30 these roads started a new copy of the app on their own. The launcher read that quit as the owner closing the app and stopped, and the new copy still believed a launcher was behind it, so the next Restart shut the app down with nothing to bring it back — on 2026-10-30 it stayed down for over two hours. Turning Safe Mode on or off is the one road that still starts its own copy, because the launcher cannot pass the Safe Mode flag; after using it in a dev install, start the app with npm run dev again before relying on Restart. Contract: restart-amc-invariants-mechanism-contract.md (I10a).
When a dev restart's freshly built code cannot start at all — or the pre-restart check refuses to switch to it — the launcher puts back an older build that is known to work, so the app comes back instead of staying down. That recovery used to be silent, which made a stale app look current. It now says so: one inbox card names the build that could not start, gives a plain-language reason, and states that the newest changes are not in the running copy, with a link to the troubleshooting view. The LAUNCHER raises that card itself, through the running app's control server, once the app is up — so it appears even when the build it fell back to is older than the notice. A refusal says so in its own words: the restart was refused, which startup check failed, and that the older build is still running. A failure's own card is never doubled: the launcher posts under the same key the failing path already uses. The session that asked for the restart is told the same thing, and the launcher carries that session's id into the fallback record so the app's notice still finds it when the restart record was already consumed. The same facts are readable at any time on GET /status (the launchFallback field of the authenticated body: that the running build is a fallback, which build failed, which build is running, the reason, the raw line, and when). A repeat of the same broken build does not stack notices, while a different one always surfaces. Nothing about when the fallback happens changed.
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.
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
Last verified 2026-11-06