@@ -0,0 +1,10 @@
+---
+'@object-ui/app-shell': patch
+---
+
+fix(app-shell): Installed Apps shows the engine's reason for an app whose register it refused at boot
+
+Clause-②: no
+Metadata-protocol: none
+
+Since `@objectstack/cloud-connection` lists a ledgered install whose register the engine refuses at boot as `notLoaded: { code, message }`, the install-local marker is a closed union of two arms: the protocol arm `{ code: 'OS_PROTOCOL_INCOMPATIBLE', requiredRange }` and the register-refusal arm `{ code, message }`, where `message` is the engine's own sentence. The console typed the marker as the protocol arm only and never read `message`, so a register-refused app read "Not loaded" with its code and no reason. `LocalInstallNotLoaded` now mirrors the two arms, and one reader, `MarketplaceNotLoadedReason`, draws the reason on both the Setup → Packages row and the package page header. The protocol arm reads exactly as before. The register-refusal arm reads the existing "did not load this package (CODE)" sentence followed by the engine's sentence, so the operator can tell whether to uninstall the app or fix the package. The engine's sentence is drawn as text, never as markup. A marker with no sentence, or an empty one, reads with the code alone, as before. No language pack changes.
@@ -64,6 +64,7 @@ import { PluginDisclosure } from './PluginDisclosure.js';
 import { MarketplaceAccessDenied } from './MarketplaceAccessDenied.js';
 import { MarketplaceResolving } from './MarketplaceResolving.js';
 import { MarketplaceDisabled } from './MarketplaceDisabled.js';
+import { MarketplaceNotLoadedReason } from './MarketplaceRowActions.js';
 import { localizePackage } from './usePackageL10n.js';
 import { isNewerVersion } from './versionPrecedence.js';
 import {
@@ -86,7 +87,6 @@ import {
   type MarketplaceDetailResponse,
   type CloudEnvironment,
   type LocalInstallEntry,
-  type LocalInstallNotLoaded,
   type LocalInstallMode,
   type LocalInstallStrippedLock,
   type CloudInstallationInfo,
@@ -1035,16 +1035,12 @@ function MarketplacePackagePageBody() {
       {t('marketplace.detail.installedV', { version: localInstall.version })}
     </Badge>
   ));
-  // The reason in plain words. A code the console has no sentence for is still
-  // read as not loaded, naming the code — Installed Apps' reading of the marker.
-  const notLoadedReason = (marker: LocalInstallNotLoaded): string =>
-    marker.code === 'OS_PROTOCOL_INCOMPATIBLE'
-      ? t('marketplace.notLoaded.protocolIncompatible', { requiredRange: marker.requiredRange })
-      : t('marketplace.notLoaded.otherReason', { code: marker.code });
+  // The reason in plain words, through Installed Apps' one reader of the
+  // marker: the protocol range, or the code with the engine's sentence.
   const localNotLoadedReason = localInstall?.notLoaded && (
     <p className="text-xs text-destructive mt-2 flex items-start gap-1.5">
       <AlertCircle className="h-3.5 w-3.5 mt-px shrink-0" aria-hidden="true" />
-      <span>{notLoadedReason(localInstall.notLoaded)}</span>
+      <MarketplaceNotLoadedReason marker={localInstall.notLoaded} />
     </p>
   );
   const localMenu = localInstall && (
 
@@ -37,25 +37,59 @@ import {
 } from '@object-ui/components';
 import { AlertCircle, ExternalLink, Trash2 } from 'lucide-react';
 import { useObjectTranslation } from '@object-ui/i18n';
-import { uninstallLocal, type LocalInstallEntry, type LocalInstallNotLoaded } from './marketplaceApi.js';
+import {
+  uninstallLocal,
+  type LocalInstallEntry,
+  type LocalInstallNotLoaded,
+  type LocalInstallNotLoadedProtocol,
+} from './marketplaceApi.js';
+
+/** The protocol arm, told by its code alone, as the console has always read it. */
+const isProtocolMarker = (marker: LocalInstallNotLoaded): marker is LocalInstallNotLoadedProtocol =>
+  marker.code === 'OS_PROTOCOL_INCOMPATIBLE';
+
+/** The engine's sentence on a register-refusal marker, or '' when it carries none. */
+const engineMessageOf = (marker: LocalInstallNotLoaded): string =>
+  'message' in marker && typeof marker.message === 'string' ? marker.message.trim() : '';
 
 /**
- * The reason a `notLoaded` entry was refused, in plain words (objectui#11645).
- * A code the console has no sentence for still reads as not loaded, naming
- * the code, rather than hiding the row the operator needs to uninstall.
+ * The reason a `notLoaded` entry was refused, in plain words: the ONE reader of
+ * the marker, drawn by Installed Apps' row ({@link MarketplaceNotLoaded}) and
+ * the package page's header (objectui#11645, objectui#11760).
+ *
+ * - The protocol arm names the range the package targets.
+ * - Any other code reads as not loaded, naming the code, rather than hiding the
+ *   row the operator needs to uninstall. On the register-refusal arm the
+ *   engine's sentence follows it (objectstack#31566), so the operator can tell
+ *   whether to uninstall the app or fix the package. It is server text and is
+ *   drawn as a text node, never as markup. A marker with no sentence, or an
+ *   empty one, reads with the code alone.
  */
+export function MarketplaceNotLoadedReason({ marker }: { marker: LocalInstallNotLoaded }) {
+  const { t } = useObjectTranslation();
+  if (isProtocolMarker(marker)) {
+    return <span>{t('marketplace.notLoaded.protocolIncompatible', { requiredRange: marker.requiredRange })}</span>;
+  }
+  const sentence = t('marketplace.notLoaded.otherReason', { code: marker.code });
+  const engineMessage = engineMessageOf(marker);
+  if (!engineMessage) return <span>{sentence}</span>;
+  return (
+    <span className="min-w-0">
+      <span>{sentence}</span>{' '}
+      <span className="block break-words" data-testid="marketplace-not-loaded-engine-message">{engineMessage}</span>
+    </span>
+  );
+}
+
+/** A `notLoaded` entry's badge and its reason (objectui#11645). */
 export function MarketplaceNotLoaded({ marker }: { marker: LocalInstallNotLoaded }) {
   const { t } = useObjectTranslation();
-  const reason =
-    marker.code === 'OS_PROTOCOL_INCOMPATIBLE'
-      ? t('marketplace.notLoaded.protocolIncompatible', { requiredRange: marker.requiredRange })
-      : t('marketplace.notLoaded.otherReason', { code: marker.code });
   return (
     <div className="flex flex-col gap-1">
       <Badge variant="destructive" className="self-start">{t('marketplace.notLoaded.badge')}</Badge>
       <p className="text-xs text-destructive flex items-start gap-1.5">
         <AlertCircle className="h-3.5 w-3.5 mt-px shrink-0" aria-hidden="true" />
-        <span>{reason}</span>
+        <MarketplaceNotLoadedReason marker={marker} />
       </p>
     </div>
   );
 
@@ -256,3 +256,62 @@ describe('Details — a refusal code the console has no sentence for (objectui#1
     expect(screen.queryByText(fill(en.marketplace.detail.installedV, { version: '3.2.0' }))).toBeNull();
   });
 });
+
+/**
+ * objectstack#31566 (PR objectstack#31650) adds the marker's second arm,
+ * `{ code, message }`: the engine refused the package's register at boot, and
+ * `message` is its own sentence. The header reads it through Installed Apps'
+ * one reader (`MarketplaceNotLoadedReason`): the code's sentence, then the
+ * engine's, as text. A marker with no sentence, or an empty one, reads with the
+ * code alone. The protocol arm is pinned unchanged by the cases above.
+ */
+const ENGINE_MESSAGE =
+  'Package "com.example.crm" declares the default page "crm_home", which is not a record page: '
+  + 'a default page must be a record page of its object.';
+const REGISTER_REFUSED = { ...REFUSED, notLoaded: { code: 'INVALID_METADATA', message: ENGINE_MESSAGE } };
+
+describe.each([
+  ['en', EN, en as Pack],
+  ['zh', ZH, zh as unknown as Pack],
+])('Details — a register-refused local install shows the engine\'s reason (objectstack#31566) [%s]', (_lang, config, pack) => {
+  const sentence = fill(pack.marketplace.notLoaded.otherReason, { code: 'INVALID_METADATA' });
+
+  describe.each([
+    ['the catalog view (marketplace on)', true],
+    ['the offline local view (marketplace off, objectui#11627)', false],
+  ])('%s', (_view, marketplace) => {
+    it('the header carries the not-loaded badge, the code\'s sentence and the engine\'s sentence', async () => {
+      await boot(marketplace, REGISTER_REFUSED);
+      renderPage(config);
+
+      expect(await screen.findByText(pack.marketplace.notLoaded.badge)).toBeInTheDocument();
+      expect(screen.getByText(sentence)).toBeInTheDocument();
+      expect(screen.getByText(ENGINE_MESSAGE)).toBeInTheDocument();
+      expect(screen.queryByText(fill(pack.marketplace.detail.installedV, { version: '3.2.0' }))).toBeNull();
+    });
+  });
+});
+
+describe('Details — the engine\'s sentence is server text (objectstack#31566)', () => {
+  it('a sentence shaped like markup is drawn as its literal text, never as elements', async () => {
+    const markup = 'Object <b>crm_lead</b> is owned by package "com.example.base".';
+    await boot(true, { ...REFUSED, notLoaded: { code: 'OBJECT_OWNERSHIP_CONFLICT', message: markup } });
+    renderPage(EN);
+
+    expect(await screen.findByText(markup)).toBeInTheDocument();
+    expect(document.body.querySelector('b')).toBeNull();
+  });
+
+  it.each([
+    ['no `message` member', { code: 'INVALID_METADATA' }],
+    ['an empty `message`', { code: 'INVALID_METADATA', message: '' }],
+    ['a blank `message`', { code: 'INVALID_METADATA', message: '   ' }],
+  ])('a marker with %s reads with the code alone', async (_case, notLoaded) => {
+    await boot(true, { ...REFUSED, notLoaded });
+    renderPage(EN);
+
+    expect(await screen.findByText(en.marketplace.notLoaded.badge)).toBeInTheDocument();
+    expect(screen.getByText(fill(en.marketplace.notLoaded.otherReason, { code: 'INVALID_METADATA' }))).toBeInTheDocument();
+    expect(screen.queryByTestId('marketplace-not-loaded-engine-message')).toBeNull();
+  });
+});
@@ -433,3 +433,69 @@ describe('no pack\'s uninstall texts say the app stays until a restart (objectui
     expect(value).not.toBe(enByKey.get(key));
   });
 });
+
+/**
+ * objectstack#31566 (PR objectstack#31650) adds the marker's second arm,
+ * `{ code, message }`: the engine refused the package's register at boot, and
+ * `message` is its own sentence. The row reads it through the one reader
+ * (`MarketplaceNotLoadedReason`): the code's sentence, then the engine's, as
+ * text, so the operator can tell whether to uninstall or fix the package. A
+ * marker with no sentence, or an empty one, reads with the code alone. The
+ * protocol arm is pinned unchanged by the cases above.
+ */
+const ENGINE_MESSAGE =
+  'Package "com.example.crm" declares the default page "crm_home", which is not a record page: '
+  + 'a default page must be a record page of its object.';
+const REGISTER_REFUSED = { ...REFUSED, notLoaded: { code: 'INVALID_METADATA', message: ENGINE_MESSAGE } };
+
+describe.each([
+  ['en', EN, en as Pack],
+  ['zh-Hans', ZH, zh as unknown as Pack],
+])('Packages — a register-refused marketplace install shows the engine\'s reason (objectstack#31566) [%s]', (_lang, config, pack) => {
+  it('the row carries the badge, the code\'s sentence and the engine\'s sentence, and Uninstall', async () => {
+    await serve([REGISTER_REFUSED, LOADED]);
+    renderPackages(config);
+
+    const r = await row('com.example.crm');
+    expect(within(r).getByText(pack.marketplace.notLoaded.badge)).toBeInTheDocument();
+    expect(within(r).getByText(fill(pack.marketplace.notLoaded.otherReason, { code: 'INVALID_METADATA' }))).toBeInTheDocument();
+    expect(within(r).getByText(ENGINE_MESSAGE)).toBeInTheDocument();
+    expect(within(r).getByRole('button', { name: pack.marketplace.action.uninstall })).toBeEnabled();
+  });
+
+  it('control: the protocol marker beside it reads exactly as before, with no engine sentence', async () => {
+    await serve([REGISTER_REFUSED, { ...REFUSED, packageId: 'com.example.old', manifestId: 'com.example.old' }]);
+    renderPackages(config);
+
+    const r = await row('com.example.old');
+    expect(within(r).getByText(fill(pack.marketplace.notLoaded.protocolIncompatible, { requiredRange: '^16' }))).toBeInTheDocument();
+    expect(within(r).queryByTestId('marketplace-not-loaded-engine-message')).toBeNull();
+    expect(r.textContent).not.toContain(ENGINE_MESSAGE);
+  });
+});
+
+describe('Packages — the engine\'s sentence on a row is server text (objectstack#31566)', () => {
+  it('a sentence shaped like markup is drawn as its literal text, never as elements', async () => {
+    const markup = 'Object <b>crm_lead</b> is owned by package "com.example.base".';
+    await serve([{ ...REFUSED, notLoaded: { code: 'OBJECT_OWNERSHIP_CONFLICT', message: markup } }]);
+    renderPackages(EN);
+
+    const r = await row('com.example.crm');
+    expect(within(r).getByText(markup)).toBeInTheDocument();
+    expect(r.querySelector('b')).toBeNull();
+  });
+
+  it.each([
+    ['no `message` member', { code: 'INVALID_METADATA' }],
+    ['an empty `message`', { code: 'INVALID_METADATA', message: '' }],
+    ['a blank `message`', { code: 'INVALID_METADATA', message: '   ' }],
+  ])('a marker with %s reads with the code alone', async (_case, notLoaded) => {
+    await serve([{ ...REFUSED, notLoaded }]);
+    renderPackages(EN);
+
+    const r = await row('com.example.crm');
+    expect(within(r).getByText(en.marketplace.notLoaded.badge)).toBeInTheDocument();
+    expect(within(r).getByText(fill(en.marketplace.notLoaded.otherReason, { code: 'INVALID_METADATA' }))).toBeInTheDocument();
+    expect(within(r).queryByTestId('marketplace-not-loaded-engine-message')).toBeNull();
+  });
+});
@@ -783,20 +783,38 @@ export async function purgeSampleData(installationId: string): Promise<SampleDat
 
 /**
  * The marker the install-local listing puts on an entry this runtime's startup
- * rehydrate refused to load (objectstack#21822, served since `@objectstack/*`
- * 17.7.0). CLOSED on the server: exactly these two members.
+ * rehydrate refused to load. CLOSED on the server (`NotLoadedMarker` in
+ * `@objectstack/cloud-connection`): exactly one of these two arms, each with
+ * exactly these members.
  *
- * `code` is the refusal's error code. The one the server sends today is
- * `OS_PROTOCOL_INCOMPATIBLE`, and `requiredRange` is then the protocol range the
- * package declares (the same `requiredRange` the install door's 422 carries in
- * `error.details`). It is typed `string` rather than that literal because the
- * console names a code it has no sentence for instead of hiding the row.
+ * - {@link LocalInstallNotLoadedProtocol}: the package targets a protocol range
+ *   this runtime does not support (objectstack#21822, served since
+ *   `@objectstack/*` 17.7.0).
+ * - {@link LocalInstallNotLoadedRefused}: the engine refused the package's
+ *   register (objectstack#31566): `code` is the refusal's ADR-0112 code and
+ *   `message` the engine's own sentence, the one the boot logs.
+ *
+ * Read the reason through `notLoadedReason` (`MarketplaceRowActions.tsx`),
+ * the one reader both Installed Apps and the package page draw.
  */
-export interface LocalInstallNotLoaded {
-  code: string;
+export type LocalInstallNotLoaded = LocalInstallNotLoadedProtocol | LocalInstallNotLoadedRefused;
+
+/** The protocol arm: `requiredRange` is the range the package declares (the same `requiredRange` the install door's 422 carries in `error.details`). */
+export interface LocalInstallNotLoadedProtocol {
+  code: 'OS_PROTOCOL_INCOMPATIBLE';
   requiredRange: string;
 }
 
+/**
+ * The register-refusal arm. `code` is typed `string` because the engine's
+ * refusal codes are open to this console: it names a code it has no sentence
+ * for instead of hiding the row. `message` is server text, drawn as text.
+ */
+export interface LocalInstallNotLoadedRefused {
+  code: string;
+  message: string;
+}
+
 /**
  * One item of `GET /api/v1/marketplace/install-local` (`listLocalInstalls`), and
  * the shape `listInstalledPackages` maps the control plane's rows into.