@knowzai/cli 0.4.0 → 0.5.1

package/dist/lib/platform-frontdoor.js

@@ -1,18 +1,23 @@
-import { readFileSync } from 'node:fs';
+import { validateSelfHostedSetupOptions } from './setup-capabilities.js';
+import { hasAdmittedPlatformImages } from './platform-image-admission.js';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { registerSecret, getPlatformDefaultProvider, setPlatformDefaultProvider, } from '@knowzai/core';
 import { applyPlatform, resolvePackagedAssetsDir, } from './platform-lifecycle.js';
 import { parseEnv, redactPlatformSecrets, } from './platform-runtime.js';
 import { resolveProviderSelection, } from './platform-provider-prompt.js';
-import { acquireGhcrLogin, detectRepoCheckout, resolveImageSource } from './platform-image-source.js';
+import { acquireGhcrLogin, resolveImageSource } from './platform-image-source.js';
 import { resolveEditionIntent, shouldUseSelfHostedEdition } from './platform-edition.js';
-import { STABLE_SELFHOSTED_RELEASE, applySelfHosted, resolvePackagedSelfHostedAssetsDir, selfHostedToPlatformResult, } from './selfhosted-lifecycle.js';
+import { STABLE_SELFHOSTED_RELEASE, applySelfHostedAsync, resolvePackagedSelfHostedAssetsDir, selfHostedToPlatformResult, } from './selfhosted-lifecycle.js';
 import { runOnboarding, runOnboardingProviderProbe, waitForOnboardingReady, DEFAULT_LOCAL_PROFILE, } from './platform-onboarding.js';
 import { ensureEngineReady as ensureContainerEngineReady, } from './container-engine.js';
 import { withSpinner } from './ui.js';
 import { buildRegistryLoginInvocation } from './platform-image-source.js';
-import { parsePlatformReleaseManifest, PlatformReleaseCatalogHttpError, releaseFreshnessNotice, resolvePlatformRelease, SelfServeResolutionError, } from './platform-release-manifest.js';
+import { catalogStaleError, newestManifestVersion, parsePlatformReleaseManifest, PlatformReleaseCatalogHttpError, releaseFreshnessNotice, resolvePlatformRelease, SelfServeResolutionError, } from './platform-release-manifest.js';
+import { pullRegistryOriginFromSource, registryNotOciError, } from './oci-registry-probe.js';
+import { catalogLagsPackagedPin } from './release-pin-matrix.js';
 import { normalizeMothershipOrigin, } from './activate.js';
+import { discoverRuntime } from './runtime-discovery.js';
 import { AGE_ELIGIBILITY_TEXT, AGE_ELIGIBILITY_UNDER_13_MESSAGE } from './login.js';
 import { KnowzError, ExitCode } from '@knowzai/core';
 /**
@@ -36,7 +41,7 @@ import { KnowzError, ExitCode } from '@knowzai/core';
  * up.test.ts anti-rot tripwire). The /release-platform skill bumps BOTH in the
  * same release commit; bump one without the other and the tripwire goes red.
  */
-export const STABLE_PORTABLE_RELEASE = '0.44.1';
+export const STABLE_PORTABLE_RELEASE = '0.47.8';
 export const DEFAULT_PORTABLE_VERSION = STABLE_PORTABLE_RELEASE;
 const DEFAULT_INSTANCE_NAME = 'knowz';
 /**
@@ -102,6 +107,88 @@ function licenseRequiredError(preflight) {
     const detail = sanitizeProblemDetail(preflight.detail);
     return new SelfServeResolutionError(`${detail ?? LICENSE_REQUIRED_FALLBACK} ${LICENSE_REQUIRED_REMEDIATION}`, 'LICENSE_REQUIRED');
 }
+function registryAuthUnreachable(mothershipUrl) {
+    return new SelfServeResolutionError(`Could not reach the Knowz image authorization service at ${mothershipUrl}/api/v1/registry/token. ` +
+        'Check your network connection, then retry.', 'REGISTRY_AUTH_UNREACHABLE');
+}
+/**
+ * Commercial grant / entitlement preflight for paid portable pulls.
+ * `GHCR_PULL_TOKEN` may authenticate to GHCR after this returns; it must never skip this gate.
+ */
+async function resolveEntitledInstallation(input) {
+    const { deps, mothershipUrl, log } = input;
+    if (!deps.loadStoredActivation || !deps.preflightRegistryCredential) {
+        throw new Error('Portable image authorization dependencies are not configured.');
+    }
+    let activation = await deps.loadStoredActivation({
+        projectName: input.projectName,
+        configDir: input.configDir,
+        engine: input.engine,
+    });
+    let activatedNow = false;
+    if (!activation) {
+        if (input.json || !deps.activateInstallation)
+            throw activationRequired();
+        log("This device isn't linked to a Knowz account yet.");
+        log('Linking is free and takes about a minute — your browser will open so you can approve this device.');
+        log('');
+        try {
+            activation = await deps.activateInstallation({
+                projectName: input.projectName,
+                configDir: input.configDir,
+                mothershipUrl,
+                engine: input.engine,
+            });
+            activatedNow = true;
+        }
+        catch {
+            throw e5();
+        }
+    }
+    let preflight = await deps.preflightRegistryCredential({ mothershipUrl, activation });
+    if (preflight.kind === 'transport-failure')
+        throw registryAuthUnreachable(mothershipUrl);
+    let preflightStatus = preflight.status;
+    if (preflightStatus === 403)
+        throw licenseRequiredError(preflight);
+    if (preflightStatus === 410)
+        throw e4(activation.installationId);
+    if (preflightStatus === 401) {
+        if (activatedNow || !input.canPrompt || !deps.confirmReactivation || !deps.activateInstallation) {
+            throw new SelfServeResolutionError(`Stored installation ${activation.installationId} is no longer valid. Run 'knowz activate' to link this device again.`, 'INSTALLATION_INVALID');
+        }
+        const accepted = await deps.confirmReactivation(activation.installationId);
+        if (!accepted)
+            throw e5();
+        try {
+            activation = await deps.activateInstallation({
+                projectName: input.projectName,
+                configDir: input.configDir,
+                mothershipUrl,
+                engine: input.engine,
+            });
+            activatedNow = true;
+        }
+        catch {
+            throw e5();
+        }
+        preflight = await deps.preflightRegistryCredential({ mothershipUrl, activation });
+        if (preflight.kind === 'transport-failure')
+            throw registryAuthUnreachable(mothershipUrl);
+        preflightStatus = preflight.status;
+        if (preflightStatus === 403)
+            throw licenseRequiredError(preflight);
+        if (preflightStatus === 410)
+            throw e4(activation.installationId);
+    }
+    if (preflightStatus !== 200) {
+        throw new SelfServeResolutionError(`Knowz could not authorize installation ${activation.installationId} for image pulls (HTTP ${preflightStatus}).`, 'INSTALLATION_INVALID');
+    }
+    registerSecret(activation.credential);
+    if (activatedNow)
+        log(`✓ Linked — installation "${input.projectName}"`);
+    return activation;
+}
 function sanitizeProblemDetail(detail) {
     if (typeof detail !== 'string' || detail.length === 0)
         return undefined;
@@ -188,19 +275,28 @@ function emitNextSteps(log) {
 }
 export async function runFrontDoor(input, deps) {
     const log = input.json
-        ? (_line) => { }
+        ? deps.progressLog ?? ((_line) => { })
         : deps.log ?? ((line) => console.log(line));
+    const explicitIntent = resolveEditionIntent({ flags: { edition: input.edition }, env: deps.env });
+    const existing = discoverRuntime({ name: input.base.name, configDir: input.base.configDir, edition: explicitIntent.explicit ? explicitIntent.edition : undefined });
+    const editionIntent = resolveEditionIntent({ flags: { edition: input.edition }, env: deps.env, existingEdition: existing?.edition });
+    const useSelfHosted = shouldUseSelfHostedEdition({ intent: editionIntent, imageFlags: input.imageFlags });
+    if (useSelfHosted)
+        validateSelfHostedSetupOptions({ provider: input.providerFlags.ai, storage: input.base.storage, publicUrls: input.base.publicUrls, orgName: input.base.orgName, seedDemo: input.seedDemo, components: input.base.components, axes: input.base.axes });
+    const checkCanceled = () => { if (input.signal?.aborted)
+        throw Object.assign(new Error('Setup canceled. Runtime data has been preserved.'), { code: 'SETUP_CANCELED', exitCode: 130 }); };
+    checkCanceled();
     const ports = {
-        api: input.base.ports?.api ?? 5000,
-        web: input.base.ports?.web ?? 3000,
-        mcp: input.base.ports?.mcp ?? 3001,
-        publicSite: input.base.ports?.publicSite ?? 3002,
+        api: input.base.ports?.api ?? existing?.state.ports.api ?? 5000,
+        web: input.base.ports?.web ?? existing?.state.ports.web ?? 3000,
+        mcp: input.base.ports?.mcp ?? existing?.state.ports.mcp ?? 3001,
+        publicSite: input.base.ports?.publicSite ?? existing?.state.ports.publicSite ?? 3002,
     };
     // 0) Environment-only preflight. It deliberately runs before config loading
     // or provider prompting so credentials are never collected on an unusable host.
     let engine;
     if (deps.preflight) {
-        let report = await deps.preflight({ name: input.base.name, configDir: input.base.configDir, ports });
+        let report = await deps.preflight({ name: input.base.name, configDir: input.base.configDir, ports, components: input.base.components ?? existing?.state.components, edition: editionIntent.edition });
         engine = report.engine;
         if (!report.ok) {
             const machineIsFixable = report.engine?.engine === 'podman'
@@ -212,7 +308,7 @@ export async function runFrontDoor(input, deps) {
                 ? withSpinner
                 : async (_text, run) => run();
             await (deps.ensureEngineReady ?? ensureContainerEngineReady)(report.engine, deps.runner, progress);
-            report = await deps.preflight({ name: input.base.name, configDir: input.base.configDir, ports });
+            report = await deps.preflight({ name: input.base.name, configDir: input.base.configDir, ports, components: input.base.components ?? existing?.state.components, edition: editionIntent.edition });
             engine = report.engine;
             if (!report.ok)
                 throwPreflightFailure(report);
@@ -220,7 +316,7 @@ export async function runFrontDoor(input, deps) {
     }
     // 1) AI-provider picker (flags → persisted default → interactive → offline fallback).
     const cfg = deps.loadConfig();
-    const cfgDefault = getPlatformDefaultProvider(cfg);
+    const cfgDefault = existing?.state.provider ?? getPlatformDefaultProvider(cfg);
     const canPrompt = deps.isTty && !input.json;
     const interactivePromptOccurred = canPrompt &&
         !input.providerFlags.offline &&
@@ -277,6 +373,7 @@ export async function runFrontDoor(input, deps) {
     }
     const applyInput = {
         ...input.base,
+        version: input.versionExplicit ? input.base.version : existing?.state.version ?? input.base.version,
         provider: selection.provider,
         azure: selection.azure ?? input.base.azure,
         gcp: selection.gcp ?? input.base.gcp,
@@ -286,80 +383,57 @@ export async function runFrontDoor(input, deps) {
     };
     // 2) Edition then image source. Unentitled `knowz up` uses public selfhosted
     //    images; the portable resolver is unchanged when edition is portable.
-    const envForEdition = input.ghcrToken
-        ? { ...deps.env, GHCR_PULL_TOKEN: input.ghcrToken }
-        : deps.env;
-    const editionIntent = resolveEditionIntent({
-        flags: { edition: input.edition },
-        env: envForEdition,
-    });
-    const checkoutDetected = Boolean(detectRepoCheckout(deps.cwd, deps.pathExists));
-    let useSelfHosted = shouldUseSelfHostedEdition({
-        intent: editionIntent,
-        imageFlags: input.imageFlags,
-        checkoutDetected,
-    });
-    // R-ED3: omitted edition + stored kzin_ may promote to portable after a 200
-    // preflight. 403/401/410/transport stay selfhosted and MUST NOT reactivate.
-    if (useSelfHosted &&
-        !editionIntent.explicit &&
-        deps.loadStoredActivation &&
-        deps.preflightRegistryCredential) {
-        const mothershipUrl = normalizeMothershipOrigin(deps.env.KNOWZ_LICENSING_MOTHERSHIP_URL?.trim() || DEFAULT_MOTHERSHIP_URL);
-        try {
-            const stored = await deps.loadStoredActivation({
-                projectName: input.base.name,
-                configDir: input.base.configDir,
-                engine: engine ?? LEGACY_DOCKER_ENGINE,
-            });
-            if (stored) {
-                const preflight = await deps.preflightRegistryCredential({
-                    mothershipUrl,
-                    activation: stored,
-                });
-                if (preflight.kind === 'http-response' && preflight.status === 200) {
-                    useSelfHosted = false;
-                }
-                else {
-                    log('Stored installation is not entitled for portable images; using public selfhosted.');
-                }
+    const savedRuntimeEnv = existing && existsSync(existing.paths.envFile) ? parseEnv(readFileSync(existing.paths.envFile, 'utf8')) : {};
+    const envForEdition = { ...deps.env, KNOWZ_REGISTRY: deps.env.KNOWZ_REGISTRY ?? savedRuntimeEnv.KNOWZ_REGISTRY, ...(input.ghcrToken ? { GHCR_PULL_TOKEN: input.ghcrToken } : {}) };
+    const cachedRestart = !useSelfHosted && existing && input.base.action === 'up'
+        && (!input.versionExplicit || input.base.version === existing.state.version)
+        && !input.imageFlags.build && !input.imageFlags.pull && !deps.env.KNOWZ_REGISTRY
+        && await (deps.admittedImages ?? hasAdmittedPlatformImages)({ name: input.base.name, version: existing.state.version, paths: existing.paths, engine: engine ?? LEGACY_DOCKER_ENGINE, components: existing.state.components ?? { mcp: true, publicSite: false } }, deps.asyncRunner ?? deps.runner);
+    const source = cachedRestart
+        ? { mode: 'preloaded', composeFile: existing.paths.composeFile, projectDir: existing.paths.runtimeDir, composePlan: 'config-up' }
+        : useSelfHosted
+            ? {
+                mode: 'pull',
+                composeFile: 'selfhosted',
+                projectDir: 'selfhosted',
+                composePlan: 'config-pull-up',
             }
-        }
-        catch {
-            // Default knowz up must not fail because a mothership probe threw.
-        }
-    }
-    const source = useSelfHosted
-        ? {
-            mode: 'pull',
-            composeFile: 'selfhosted',
-            projectDir: 'selfhosted',
-            composePlan: 'config-pull-up',
-        }
-        : resolveImageSource({
-            cwd: deps.cwd,
-            flags: input.imageFlags,
-            canPrompt: deps.isTty && Boolean(deps.ghcrPrompt),
-            pathExists: deps.pathExists,
-            packagedAssetsDir: deps.packagedAssetsDir,
-            env: envForEdition,
-        });
+            : resolveImageSource({
+                cwd: deps.cwd,
+                flags: input.imageFlags,
+                canPrompt: deps.isTty && Boolean(deps.ghcrPrompt),
+                pathExists: deps.pathExists,
+                packagedAssetsDir: deps.packagedAssetsDir,
+                env: envForEdition,
+            });
     const seam = source.mode === 'build'
         ? { composeFile: source.composeFile, projectDir: source.projectDir, composePlan: source.composePlan }
         : source.mode === 'pull'
             ? { composePlan: source.composePlan, registry: 'registry' in source ? source.registry ?? null : null }
             : { composePlan: source.composePlan };
+    const resultImageMode = cachedRestart ? existing.state.imageMode ?? 'pull' : source.mode;
+    if (input.imageFlags.pull)
+        seam.forceAcquisition = true;
     // §2026-08-31 R7: portable images are linux/amd64-only. Selfhosted GHCR is multi-arch.
     const hostArch = deps.hostArch ?? process.arch;
     if (!useSelfHosted && hostArch === 'arm64' && (source.mode === 'pull' || source.mode === 'preloaded')) {
         log('Note: knowz images run under amd64 emulation on this Mac; native arm64 images are not yet published.');
     }
     const selfServePlan = source.loginPlan?.kind === 'self-serve' ? source.loginPlan : undefined;
+    // #862: fail closed when the advertised facade is SPA HTML, not OCI.
+    // Skip when probeRegistry is omitted so injected unit tests stay network-free.
+    const pullOrigin = pullRegistryOriginFromSource(source);
+    if (pullOrigin && deps.probeRegistry) {
+        const probe = await deps.probeRegistry(pullOrigin);
+        if (!probe.ok)
+            throw registryNotOciError(pullOrigin, probe);
+    }
     if (selfServePlan) {
         const mothershipUrl = normalizeMothershipOrigin(deps.env.KNOWZ_LICENSING_MOTHERSHIP_URL?.trim() || DEFAULT_MOTHERSHIP_URL);
         const manifestUrl = `${mothershipUrl}${RELEASE_MANIFEST_PATH}`;
         log('◇ Checking Knowz releases…');
         let manifest;
+        let catalogFromMothership = true;
         try {
             const raw = await (deps.fetchReleaseManifest ?? defaultFetchReleaseManifest)(manifestUrl);
             // Parsing stays outside the fallback contract: a malformed 200 is a server
@@ -390,6 +464,7 @@ export async function runFrontDoor(input, deps) {
                     ? await deps.loadPackagedReleaseManifest(fallbackPath)
                     : JSON.parse(readFileSync(fallbackPath, 'utf8'));
                 manifest = parsePlatformReleaseManifest(fallback);
+                catalogFromMothership = false;
             }
             catch {
                 throw e1(manifestUrl);
@@ -397,6 +472,37 @@ export async function runFrontDoor(input, deps) {
             log(`Warning: could not reach the Knowz release catalog at ${manifestUrl} — using the release list packaged with this CLI, which may be out of date.`);
         }
         const flavor = selection.provider === 'gcp' ? 'portable-gcp' : 'portable';
+        // #865: a successful but stale mothership catalog must not silently pin an
+        // older blessed row. Skip packaged-fallback, empty catalog (existing
+        // RELEASE_NOT_PUBLISHED), and an explicit pin that is still blessed.
+        if (!input.versionExplicit && catalogFromMothership) {
+            const catalogNewest = newestManifestVersion(manifest, flavor);
+            if (catalogNewest) {
+                try {
+                    const packagedPath = join(source.projectDir, 'releases.json');
+                    const packagedRaw = deps.loadPackagedReleaseManifest
+                        ? await deps.loadPackagedReleaseManifest(packagedPath)
+                        : JSON.parse(readFileSync(packagedPath, 'utf8'));
+                    const packaged = parsePlatformReleaseManifest(packagedRaw);
+                    const stale = catalogLagsPackagedPin({
+                        catalogNewest,
+                        packagedNewest: newestManifestVersion(packaged, flavor),
+                    });
+                    if (stale.stale && stale.packagedNewest) {
+                        throw catalogStaleError({
+                            manifestUrl,
+                            catalogNewest: stale.catalogNewest,
+                            packagedNewest: stale.packagedNewest,
+                        });
+                    }
+                }
+                catch (staleError) {
+                    if (staleError instanceof SelfServeResolutionError)
+                        throw staleError;
+                    // Packaged list unreadable — keep catalog resolution; do not invent a pin.
+                }
+            }
+        }
         const resolved = resolvePlatformRelease({
             manifest,
             requestedVersion: input.versionExplicit ? input.base.version : undefined,
@@ -405,6 +511,7 @@ export async function runFrontDoor(input, deps) {
             manifestUrl,
         });
         applyInput.version = resolved.release.version;
+        seam.expectedDigests = resolved.release.digests;
         if (resolved.note)
             log(resolved.note);
         log(`✓ Knowz Platform ${resolved.release.version} (${flavor}) — released ${resolved.release.releasedAt.slice(0, 10)}`);
@@ -422,7 +529,7 @@ export async function runFrontDoor(input, deps) {
         }
     }
     else if (selection.provider !== 'offline' &&
-        (source.mode === 'preloaded' || source.loginPlan?.kind === 'ghcr') &&
+        !cachedRestart && (source.mode === 'preloaded' || source.loginPlan?.kind === 'ghcr') &&
         deps.fetchReleaseManifest) {
         // §2026-08-31 R4 (ghcr-token / preloaded): no manifest resolution runs on these
         // paths, so the version about to boot is the pin/explicit choice. Advisory-only
@@ -435,6 +542,7 @@ export async function runFrontDoor(input, deps) {
             loadPackagedReleaseManifest: deps.loadPackagedReleaseManifest,
         });
         if (advisoryManifest) {
+            seam.expectedDigests = advisoryManifest.releases.find(release => release.version === (applyInput.version ?? DEFAULT_PORTABLE_VERSION) && release.flavors.includes(selection.provider === 'gcp' ? 'portable-gcp' : 'portable'))?.digests;
             const freshness = releaseFreshnessNotice({
                 currentVersion: applyInput.version ?? DEFAULT_PORTABLE_VERSION,
                 manifest: advisoryManifest,
@@ -459,7 +567,7 @@ export async function runFrontDoor(input, deps) {
     if (shouldConfirm) {
         const accepted = await deps.confirmPrompt({
             provider: selection.provider,
-            imageMode: source.mode,
+            imageMode: resultImageMode,
             version: applyInput.version ?? DEFAULT_PORTABLE_VERSION,
             ports,
             profileName: input.profileName ?? DEFAULT_LOCAL_PROFILE,
@@ -472,7 +580,7 @@ export async function runFrontDoor(input, deps) {
     setPlatformDefaultProvider(cfg, selection.provider);
     deps.saveConfig(cfg);
     const applyDeps = {
-        runner: deps.runner,
+        runner: deps.asyncRunner ?? deps.runner,
         assetsDir: deps.assetsDir,
         randomBytes: deps.randomBytes,
         now: deps.now,
@@ -482,27 +590,58 @@ export async function runFrontDoor(input, deps) {
         engine: engine ?? LEGACY_DOCKER_ENGINE,
     };
     // 3) Bring the stack up; anonymous pull first, authenticate + retry once on auth failure.
+    //    Paid GHCR pulls still require mothership grant preflight first — the token is
+    //    registry auth only and must not skip commercial entitlement (#863).
+    const entitledInstallationInput = {
+        projectName: input.base.name,
+        configDir: input.base.configDir,
+        json: input.json,
+        mothershipUrl: normalizeMothershipOrigin(deps.env.KNOWZ_LICENSING_MOTHERSHIP_URL?.trim() || DEFAULT_MOTHERSHIP_URL),
+        engine: engine ?? LEGACY_DOCKER_ENGINE,
+        canPrompt,
+        log,
+        deps,
+    };
+    let entitledActivation;
+    applyDeps.authorizeAcquisition = async () => {
+        entitledActivation ??= await resolveEntitledInstallation(entitledInstallationInput);
+        return { installationId: entitledActivation.installationId, authorizedAt: new Date().toISOString() };
+    };
     let applied;
     if (useSelfHosted) {
         log('Using public selfhosted images. Portable platform requires --edition=portable and an entitled key.');
         const selfhostedVersion = input.versionExplicit && applyInput.version
             ? applyInput.version
-            : (deps.env.KNOWZ_SELFHOSTED_VERSION?.trim() || STABLE_SELFHOSTED_RELEASE);
-        const selfhosted = applySelfHosted({
+            : (deps.env.KNOWZ_SELFHOSTED_VERSION?.trim() || existing?.state.version || STABLE_SELFHOSTED_RELEASE);
+        const selfhosted = await applySelfHostedAsync({
             name: input.base.name,
             version: selfhostedVersion,
             configDir: input.base.configDir,
             ports,
             openAiCompatible: applyInput.openAiCompatible,
             adminPassword: applyInput.superAdminPassphrase,
+            provider: selection.provider,
+            providerSettingsExplicit: Boolean(input.providerFlags.offline || input.providerFlags.ai || [input.providerFlags.azure, input.providerFlags.openAiCompatible].some(values => values && Object.values(values).some(value => value !== undefined && value !== ''))),
+            disableAI: input.providerFlags.offline || input.providerFlags.ai === 'offline' ? true : input.providerFlags.ai ? false : undefined,
+            azure: applyInput.azure,
+            components: applyInput.components,
         }, {
-            runner: deps.runner,
+            runner: deps.asyncRunner ?? deps.runner,
+            engine: engine ?? LEGACY_DOCKER_ENGINE,
+            signal: input.signal,
+            progress: log,
+            waitUntilReady: async (apiUrl, signal) => {
+                const ready = await waitForOnboardingReady({}, deps.onboardingDepsFor(apiUrl));
+                return ready && !signal?.aborted;
+            },
             randomBytes: deps.randomBytes,
             packagedAssetsDir: deps.selfHostedAssetsDir ?? resolvePackagedSelfHostedAssetsDir(),
         });
         applied = selfHostedToPlatformResult(selfhosted, selection.provider, deps.now);
     }
     else {
+        if (!cachedRestart)
+            await applyDeps.authorizeAcquisition({ name: input.base.name, mode: source.mode, engine: engine ?? LEGACY_DOCKER_ENGINE, env: deps.env });
         if (selfServePlan)
             log(`◇ Pulling images from ${selfServePlan.registry}…`);
         try {
@@ -524,84 +663,7 @@ export async function runFrontDoor(input, deps) {
                 applied = await (deps.applyPlatform ?? applyPlatform)(applyInput, applyDeps, { ...seam, login });
             }
             else if (source.mode === 'pull' && selfServePlan && isRegistryAuthError(error)) {
-                const activeEngine = engine ?? LEGACY_DOCKER_ENGINE;
-                const mothershipUrl = normalizeMothershipOrigin(deps.env.KNOWZ_LICENSING_MOTHERSHIP_URL?.trim() || DEFAULT_MOTHERSHIP_URL);
-                if (!deps.loadStoredActivation ||
-                    !deps.activateInstallation ||
-                    !deps.preflightRegistryCredential) {
-                    throw new Error('Self-serve registry authentication dependencies are not configured.');
-                }
-                let activation = await deps.loadStoredActivation({
-                    projectName: input.base.name,
-                    configDir: input.base.configDir,
-                    engine: activeEngine,
-                });
-                let activatedNow = false;
-                if (!activation) {
-                    if (input.json)
-                        throw activationRequired();
-                    log("This device isn't linked to a Knowz account yet.");
-                    log('Linking is free and takes about a minute — your browser will open so you can approve this device.');
-                    log('');
-                    try {
-                        activation = await deps.activateInstallation({
-                            projectName: input.base.name,
-                            configDir: input.base.configDir,
-                            mothershipUrl,
-                            engine: activeEngine,
-                        });
-                        activatedNow = true;
-                    }
-                    catch {
-                        throw e5();
-                    }
-                }
-                let preflight = await deps.preflightRegistryCredential({ mothershipUrl, activation });
-                if (preflight.kind === 'transport-failure') {
-                    throw new SelfServeResolutionError(`Could not reach the Knowz image authorization service at ${mothershipUrl}/api/v1/registry/token. ` +
-                        'Check your network connection, then retry.', 'REGISTRY_AUTH_UNREACHABLE');
-                }
-                let preflightStatus = preflight.status;
-                if (preflightStatus === 403)
-                    throw licenseRequiredError(preflight);
-                if (preflightStatus === 410)
-                    throw e4(activation.installationId);
-                if (preflightStatus === 401) {
-                    if (activatedNow || !canPrompt || !deps.confirmReactivation) {
-                        throw new SelfServeResolutionError(`Stored installation ${activation.installationId} is no longer valid. Run 'knowz activate' to link this device again.`, 'INSTALLATION_INVALID');
-                    }
-                    const accepted = await deps.confirmReactivation(activation.installationId);
-                    if (!accepted)
-                        throw e5();
-                    try {
-                        activation = await deps.activateInstallation({
-                            projectName: input.base.name,
-                            configDir: input.base.configDir,
-                            mothershipUrl,
-                            engine: activeEngine,
-                        });
-                        activatedNow = true;
-                    }
-                    catch {
-                        throw e5();
-                    }
-                    preflight = await deps.preflightRegistryCredential({ mothershipUrl, activation });
-                    if (preflight.kind === 'transport-failure') {
-                        throw new SelfServeResolutionError(`Could not reach the Knowz image authorization service at ${mothershipUrl}/api/v1/registry/token. ` +
-                            'Check your network connection, then retry.', 'REGISTRY_AUTH_UNREACHABLE');
-                    }
-                    preflightStatus = preflight.status;
-                    if (preflightStatus === 403)
-                        throw licenseRequiredError(preflight);
-                    if (preflightStatus === 410)
-                        throw e4(activation.installationId);
-                }
-                if (preflightStatus !== 200) {
-                    throw new SelfServeResolutionError(`Knowz could not authorize installation ${activation.installationId} for image pulls (HTTP ${preflightStatus}).`, 'INSTALLATION_INVALID');
-                }
-                registerSecret(activation.credential);
-                if (activatedNow)
-                    log(`✓ Linked — installation "${input.base.name}"`);
+                const activation = entitledActivation ?? await resolveEntitledInstallation(entitledInstallationInput);
                 const login = buildRegistryLoginInvocation(selfServePlan.registry, activation.installationId, activation.credential);
                 try {
                     applied = await (deps.applyPlatform ?? applyPlatform)(applyInput, applyDeps, {
@@ -627,9 +689,10 @@ export async function runFrontDoor(input, deps) {
             }
         }
     }
+    checkCanceled();
     for (const line of applied.output.split('\n'))
         log(line);
-    const profileName = input.profileName ?? DEFAULT_LOCAL_PROFILE;
+    const profileName = input.profileName ?? localProfileNameFor(input.base.name);
     const apiUrl = applied.state.serviceUrls.api;
     const webUrl = applied.state.serviceUrls.web;
     const renderedEnv = parseEnv(readFileSync(applied.paths.envFile, 'utf8'));
@@ -653,24 +716,37 @@ export async function runFrontDoor(input, deps) {
     // 4a) The same bounded health gate precedes every credential path, including
     //     profile reuse. Passing the result into onboarding avoids a second poll.
     const apiReady = await waitForOnboardingReady({}, onboardingDeps);
-    if (!apiReady) {
-        identity = await collectRegistrationIdentity();
-        const onboarding = await runOnboarding({ ...onboardingInput, register: identity, apiReady }, onboardingDeps);
-        emitNextSteps(log);
-        return {
-            state: applied.state,
-            imageMode: source.mode,
-            provider: selection.provider,
-            profile: onboarding.profile ?? null,
-            loginMode: onboarding.loginMode,
-            seeded: onboarding.seeded,
-            edition: useSelfHosted ? 'selfhosted' : 'portable',
-        };
+    checkCanceled();
+    if (!apiReady)
+        throw new Error('Runtime health check did not become ready. Inspect knowz runtime doctor and logs, then retry setup.');
+    if (useSelfHosted) {
+        let profile = null;
+        let nextAction;
+        try {
+            const reused = await deps.reuseExistingProfile?.(profileName, apiUrl, { dialect: 'selfhosted', signal: input.signal });
+            if (reused)
+                profile = profileName;
+            else if (deps.selfHostedLogin) {
+                const login = await deps.selfHostedLogin({ profile: profileName, apiUrl, username: renderedEnv.ADMIN_USERNAME || 'admin', password: renderedEnv.ADMIN_PASSWORD || '', signal: input.signal });
+                profile = login.profile;
+            }
+            else
+                nextAction = `Run knowz login --self-hosted --api-url ${apiUrl} --profile ${profileName} to finish CLI access.`;
+        }
+        catch (error) {
+            nextAction = `${redactPlatformSecrets(errorMessage(error), Object.values(renderedEnv))} Sign in with the current administrator password: knowz login --self-hosted --username ${renderedEnv.ADMIN_USERNAME || 'admin'} --api-url ${apiUrl} --profile ${profileName}.`;
+        }
+        checkCanceled();
+        if (input.open)
+            onboardingDeps.openBrowser(webUrl);
+        if (nextAction)
+            log(nextAction);
+        return { status: profile ? 'complete' : 'attention-required', ...(profile ? {} : { code: 'SETUP_ACTION_REQUIRED', nextAction }), state: applied.state, imageMode: 'pull', provider: selection.provider, profile, loginMode: profile ? 'existing' : 'manual', seeded: false, edition: 'selfhosted' };
     }
     // 4b) If a prior `up` already signed the CLI profile in and its key still authenticates,
     //     skip the register/onboarding dance entirely — avoids the register → "Email already
     //     registered" → manual-degrade noise on every idempotent re-up.
-    const reused = deps.reuseExistingProfile ? await deps.reuseExistingProfile(profileName, apiUrl) : null;
+    const reused = deps.reuseExistingProfile ? await deps.reuseExistingProfile(profileName, apiUrl, { dialect: 'platform' }) : null;
     if (reused) {
         await runOnboardingProviderProbe(selection.provider, () => onboardingDeps.apiClientFor(profileName), onboardingDeps);
         log(`Already signed in — reusing the '${profileName}' CLI profile${reused.tenantId ? ` (tenant ${reused.tenantId})` : ''}.`);
@@ -678,15 +754,17 @@ export async function runFrontDoor(input, deps) {
         log(`  API:    ${apiUrl}`);
         if (input.open)
             onboardingDeps.openBrowser(webUrl);
-        return { state: applied.state, imageMode: source.mode, provider: selection.provider, profile: profileName, loginMode: 'existing', seeded: false, edition: useSelfHosted ? 'selfhosted' : 'portable' };
+        return { status: 'complete', state: applied.state, imageMode: resultImageMode, provider: selection.provider, profile: profileName, loginMode: 'existing', seeded: false, edition: useSelfHosted ? 'selfhosted' : 'portable' };
     }
     // 4c) Onboarding: bootstrap → register fallback → manual degrade.
     identity = await collectRegistrationIdentity();
     const onboarding = await runOnboarding({ ...onboardingInput, register: identity, apiReady }, onboardingDeps);
     emitNextSteps(log);
     return {
+        status: onboarding.profile ? 'complete' : 'attention-required',
+        ...(onboarding.profile ? {} : { code: 'SETUP_ACTION_REQUIRED', nextAction: 'Finish account sign-in with knowz login for this endpoint.' }),
         state: applied.state,
-        imageMode: source.mode,
+        imageMode: resultImageMode,
         provider: selection.provider,
         profile: onboarding.profile ?? null,
         loginMode: onboarding.loginMode,