Manage the runtime — PexarBolt Docs

Plugin resource and reliability requirementsThe SDK's PLUGIN_OPTIMIZATION_POLICY is the shared source for developer tools. It is exposed through standalone API/MCP plugin_read.context.optimizationPolicy, Studio MCP plugin_context, and Vibe. CLI check/package and both MCP check paths return:{"verification":{"mode":"fixture","liveVerified":false,"optimizationReview":"required","policyVersion":2,"requiredLiveChecks":["Live checks for the declared capabilities"]}}ok: true means package, defaults, sandbox startup and sample controls passed. It does not statically prove every asynchronous path, complete optimization review or test real disks under load. Report the checks actually performed and the remaining work.Implementation rules

Publish initial state and return promptly from activate, within the five-second startup deadline. Do not await an entire watch/poll loop or a long network operation.

Initial state, events and timers share one serialized publisher. Start publications at least 300 ms apart, coalesce to the latest state, skip unchanged state and await the previous publication. Do not queue a publication for every file event. Four publications per second is a ceiling, not a target.

Prefer SDK subscriptions. When polling is necessary, schedule the next request after the previous one finishes; avoid overlapping asynchronous setInterval callbacks. Bound queues, history, caches, concurrency and retries. Yield between batches of expensive work.

Bind resources to ctx.signal and actions to the event signal. Stop timers, subscriptions, watchers and streams; cancel work, discard stale asynchronous results and handle background rejections. Never replay writes or ejection after an unknown outcome.

Also respect 10 logs/second, 20 HID calls/second, 100 SDK data requests/second, four concurrent HTTP requests and 16 outstanding SDK data requests.

On-demand runtimes and hidden workEnabled plugins do not run in the background. The Desktop host starts a plugin's runtime when the Dock or the Desktop simulator opens it and stops it after RUNTIME_LIFECYCLE.idleStopMs (60 seconds) hidden; reopening within that window reuses it. Native-execution projections never start one. Each hidden sandbox previously cost roughly 45–70 MB of host memory, so this keeps the App's footprint proportional to what the user is looking at.

Treat every activate as a possible resume. Persist state users expect to survive leaving the plugin (timer deadlines as wall-clock times, positions, scores, selections) with ctx.store (store permission), restore it before the first publish and recompute elapsed time from the clock.

Use ctx.view.visible and ctx.view.subscribe(listener) to pause timers, polling, slideshows, network frame pulls and render loops while hidden. Refresh once when visible again and clamp elapsed simulation time so games do not jump.

After activation, ctx.frames.present/submit wait while hidden: the newest submission is held until the plugin is shown and older waiting ones resolve accepted: false, so a loop that awaits present pauses naturally. Frames presented during activate are never held, so awaiting a first frame cannot stall startup.

For compatibility with older hosts, which lack the API and never stop hidden runtimes, use ctx.view?.visible ?? true and ctx.view?.subscribe(...). Previews and the standalone toolkit are always visible; exercise hidden behavior in the App.

Dock reconnectionThis section is the single reference for reconnect behavior; the contract's Runtime Lifecycle section summarizes the plugin rules.A Dock disconnect retires the device view and hides the plugin; its host runtime keeps running for the 60-second idle window and then stops. Updated App and firmware automatically restore the currently selected host plugin after reconnecting or losing the five-second lease, resending its latest state and cached frame without Idle → Enable; if the idle window has passed, the selected plugin's runtime starts again on demand. Catalog/view reconciliation runs every five seconds with 1–30 second failure backoff; capability negotiation has a separate backoff. Back, disabled plugins and revoked grants take precedence, and control/HID actions are never replayed. Full recovery, including lost open requests and device-only disconnection, needs the updated App and firmware; older devices still resynchronize the catalog after lease failure.Do not implement Idle/Enable or repeated open_on_device loops as recovery. Plugin network sources still need cancellable, bounded retries to their own services. Verify live and paused frames plus controls on real hardware; fixture checks cannot prove reconnect recovery.Cameras and snapshot streamsCamera and snapshot plugins read frames through ctx.http.readBytes from an authorized HTTPS origin or localhost gateway and present them with ctx.frames (see plugin media).Refresh camera metadata independently from frame polling, with at most one outstanding request, without blocking frames. On brief frame failures, retain the same camera's last good frame for a bounded grace period, show Buffering with the original timestamp and retry with capped backoff. Clear old frames on confirmed offline/access denial, camera changes or grace-period expiry. Metadata or discovery failure must not clear known cameras or tear down healthy video sessions. A gateway's idle timeout must exceed the client request timeout plus retry interval. Clear latched player errors when playback returns to playing. Test brief and sustained outages, slow discovery and camera switching against a real source.Filesystem and transfer observationThe API itself is described in the filesystem guide. Use one ctx.fs.watchExternal() subscription per plugin for all external volumes. Do not create per-volume/directory/file watchers, rescan on every notification or poll snapshots instead of subscribing. The host owns native watchers: one recursive watcher per volume on macOS/Windows avoids blocking the App while hundreds of FSEvents handles close.Callbacks execute serially and must finish within ten seconds. Update bounded state and schedule background work. Recover snapshots only on reset/revision gaps, paging at least 20 ms apart. Check mountId, epoch and revision after awaits. Transfer-only views do not need index snapshots. Name/extension filters select returned files without reducing traversal budgets. Show unavailable, not an empty disk, when indexing exceeds quota. Metadata status and transfer-status are independent: an index quota failure does not establish transfer failure.

Situation

State and display

Follow-up

Publisher pauses

paused; keep percentage, hide speed/ETA

The same task may resume as running

Publisher cancels

cancelled / publisher_cancelled

Never count as completed, even at 100%

Publisher confirms completion

completed

Deduplicate by volumeId + mountId + id

Unpublication, publisher exit, directory subscription ends

unknown / observation_ended

Do not infer success, cancellation or a specific failure

Unplug or unmount

Active tasks become unknown / volume_unmounted, then unmounted

Retain bounded terminal notices and clear active mount state

Observation backend fails

Active tasks become unknown / backend_unavailable

Show backend failure; preserve confirmed completion/cancellation

watcher.closed rejects or is explicitly closed

Observation ended, not copying completed

Mark remaining local active tasks unknown and clean up

Remount or resubscribe

New mountId and newly observed tasks

Reject stale callbacks; do not merge tasks by path

Non-running speed and ETA are null. Percentage may retain the last observation but never proves terminal state. Optional reason fields extend state; handle state even when an older host omits reason. Late running/completed events cannot overwrite host terminal states. Bursts and short tasks may be coalesced, so intermediate states are not guaranteed. Missing snapshot tasks may simply have expired or been evicted. On transfer-reset, replace the current view with transferSnapshot; mark missing active tasks unknown without inventing completion events.These APIs only observe other applications' transfers. They cannot pause, cancel or resume Finder tasks. watcher.close/signal abort stop observation; watcher.eject is an explicitly requested safe removal of the entire disk, not transfer cancellation.Diagnosis and verificationFor unavailable/runtime_fault, read plugin_runtime status/logs first. heartbeat_timeout, startup_timeout, activation_failed, event_timeout and renderer_* identify different paths. Do not classify every error as a disk permission problem or mask host failures with polling, raised quotas or disabled watchdogs.Run live for at least 60 seconds and exercise bursts, response latency, stop/restart, revocation, preview close and host sleep recovery. For external storage, also test empty disks, large/deep directories, quota failures, hot unplug/remount, scan failure, pause/resume, cancellation, publisher exit and backend failure. Completion/cancellation does not prove content verification or durable persistence. Windows and applications that do not publish NSProgress must show unsupported/unknown.Host regressions cover watcher limits, heartbeat recovery after main-thread stalls, terminal retention and mount isolation. node apps/desktop/scripts/test-plugin-file-progress.mjs verifies cross-process completion, cancellation, pause/resume and publisher exit in an isolated directory. Record actual Finder, external-disk, Windows hardware and sleep-recovery results separately.