Installation lifecycle

Current local install behavior is implemented in:

• validate_extension()
• install_dashboard_extension()
• install_developer_extension_from_path()
• uninstall_extension()

5.1 Dashboard install

Non-developer extensions are installed from dashboard extension records. The installer downloads the dashboard payload, verifies its SHA-256 digest, validates the extracted extension, and copies it into the managed extension root.

When the public manifest contains modelRecommendations, installation has an additional administrator review:

1. The host validates the recommendation schema before any dashboard mutation.
2. Each recommendation is compared with the current workspace model inventory. Display name alone never counts as a match.
3. Required missing models remain selected. Recommended missing models are selected by default but can be deselected.
4. The host adds selected missing models through the existing model API with an empty group list, then adds the extension.
5. Created models remain workspace-only until an administrator links them to groups. The extension itself keeps the existing optional link to the group from which the add-extension flow was opened.

The complete publisher and administrator procedure is in Model recommendations.

An existing normalHttp model matches only when its normalized URL and output filename match and the workspace model contains every declared model type. An existing openAICompatibleAPI model matches only when its normalized base URL and provider model identifier match and the workspace model contains every declared model type. Its stored API key is deliberately ignored during matching and is never exposed to the extension.

A missing OpenAI-compatible recommendation requires the administrator to enter an API key. That key stays in transient review state until it is passed to the existing add-model command; it is never added to extension metadata or manifestJson.

This MVP is deliberately additive rather than transactional. Models are added one by one before the extension:

• If any selected model fails, the extension is not added and the review stays open.
• If a later model or extension operation fails, models already created in the workspace remain there.
• Retrying re-runs exact matching and reuses those models instead of deleting or duplicating them.

A normalHttp recommendation registers a workspace model record only. It always uses autoDownload: false; downloading model bytes to the current device remains a separate model-library action. Likewise, adding a model to a workspace does not make it available to any group. These two follow-up actions must not be presented as part of the extension installation.

The automated recommendation review currently runs only in the dashboard Add Extension flow. Developer mounting validates the manifest without provisioning models, extension updates do not retroactively process changed recommendations, and uninstalling an extension does not remove models created during its installation.

5.2 Developer install

Developer installation mounts an extension source directory as a developer extension and is intended for development users/builds only.

5.3 Uninstall

Uninstall removes the installed or developer-mounted extension and stops extension native processes when supported.

5.3.1 Worker grant lifecycle

A package requesting dashboard_worker is staged and verified before an administrator can grant it. The grant binds the exact payload digest, version, entries, runtime, protocol, and functions. Automatic updates never retain a stale grant, and unlink, uninstall, or privilege change revokes grants and fences active jobs. See Dashboard extension workers.

5.4 Mod review and activation

An extension requesting mod has two distinct lifecycle decisions:

1. Before a manual dashboard install, update, or developer mount mutates extension inventory, the host previews validated metadata and warns that the extension can change ISA Warden and inject code outside the iframe sandbox.
2. Before each current-session host activation, the host reads authoritative installed extension info and asks for an interactive acknowledgement. Declining leaves the iframe entry usable and loads no host script, style, root, or listener.

For dashboard packages, the public distribution permissions and modEntry must match the SHA-256-verified extracted payload manifest. A mismatch fails preview, installation, or update. An update that adds or removes mod, or changes modEntry, is treated as a privilege change and must be reviewed.

Automatic dashboard synchronization may download and install a mod package, but it never activates modEntry unattended. The host module remains inert until a user opens the extension in the main application and accepts the activation warning. Detached extension windows remain iframe-only and do not mount main-shell contributions.

On close, reload, replacement, update, activation error, or host disposal, the host invokes module cleanup and removes its tracked styles, roots, scripts, and listeners. Uninstall still removes the installed extension after active contributions have been disposed.