@synopackageland/cli 0.17.3 → 0.17.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+## 0.17.4 (2026-10-19)
+
+- Accept `compose.startup_timeout_seconds` (default 120, integer 2–900), use the SDK plan's value for daemon start, and deliver the same budget to container bootstrap adapters through the SDK-generated environment. Reject a planner that cannot honor an explicitly declared budget. Keep ingress closed until readiness succeeds.
+
+- Show actionable image-pull diagnosis in nine locales and direct users to Package Center Repair when a package starts with stale container assets.
+- Pin templates 0.17.6 and SDK/App 0.17.4; keep UI at 0.12.3.
+
 ## 0.17.3 (2026-10-19)
 
 - Pin templates 0.17.5, SDK/App 0.17.3 and UI 0.12.3 for generated Apps.

package/README.md

@@ -259,6 +259,16 @@ Compose uses schema-2 `dsm-package.yaml` and `ui.launch`; the default is new-pag
 Classless gateways use type url via the shared contract/app-launch resolver;
 AppWindow wrappers use standalone. Headless projects have no launcher.
 
+Rebuilt container Apps include informational **Registry check** diagnostics in
+preinst, postinst, postupgrade and prestart. Messages use the existing nine-language
+catalog and end with the native recovery step: fix the cause, then use Package
+Center **Repair**. Repair re-runs the install worker and downloads missing images;
+it is not an SDK Retry action. Checks use only immutable image references from the
+packaged lock, never the Docker socket or registry credentials. They do not block
+cached/offline startup or establish daemon disk space, image existence or pull
+success. Native wrapper codes alone never identify a cause. SDK and CLI changes
+must ship together and Apps must be rebuilt to receive these hooks and catalogs.
+
 See [Compose](skills/reference/compose.md) for multiple upstream files,
 generated override/worker artifacts, image proofs and the support matrix.
 Containers use a fixed package identity and do not inherit a signed-in user's

package/dist/build-spk/compose-diagnosis.d.ts

@@ -0,0 +1,4 @@
+/** Packaged data for compose/control; one source of native text in all locales. */
+export declare function composeDiagnosisMessages(): Record<string, Record<string, string>>;
+/** Diagnostics are informational and cannot mask or replace a native result. */
+export declare function renderComposeDiagnosis(project: string, phase: "preinst" | "postinst" | "postupgrade" | "prestart"): string;

package/dist/build-spk/compose-diagnosis.js

@@ -0,0 +1,12 @@
+import { LOCALES } from "../standalone/i18n.js";
+import { WIZARD_MESSAGES } from "./wizard-i18n.js";
+/** Packaged data for compose/control; one source of native text in all locales. */
+export function composeDiagnosisMessages() {
+    return Object.fromEntries(LOCALES.map((locale) => [locale, Object.fromEntries(Object.entries(WIZARD_MESSAGES)
+            .filter(([key]) => key.startsWith("compose.diagnosis."))
+            .map(([key, texts]) => [key.slice("compose.diagnosis.".length), texts[locale]]))]));
+}
+/** Diagnostics are informational and cannot mask or replace a native result. */
+export function renderComposeDiagnosis(project, phase) {
+    return `"${project}/control" diagnose --project "${project}" --phase ${phase} || :\n`;
+}

package/dist/build-spk/wizard-messages.d.ts

@@ -1,4 +1,136 @@
 export declare const WIZARD_MESSAGES: {
+    "compose.diagnosis.registry_check": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.container_manager": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.tls_trust": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.unreachable": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.dns": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.rate_limit": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.disk_full": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.not_found": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.denied": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.unknown": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.repair": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "compose.diagnosis.error_code": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
     "delegate.preselection": {
         en: string;
         "zh-TW": string;

package/dist/build-spk/wizard-messages.js

@@ -1,4 +1,136 @@
 export const WIZARD_MESSAGES = {
+    "compose.diagnosis.registry_check": {
+        "en": "Registry check",
+        "zh-TW": "登錄站檢查",
+        "zh-CN": "镜像仓库检查",
+        "ja": "レジストリ確認",
+        "ko": "레지스트리 확인",
+        "de": "Registry-Prüfung",
+        "fr": "Vérification du registre",
+        "es": "Comprobación del registro",
+        "it": "Verifica del registro"
+    },
+    "compose.diagnosis.container_manager": {
+        "en": "Container Manager",
+        "zh-TW": "Container Manager 錯誤",
+        "zh-CN": "Container Manager 错误",
+        "ja": "Container Manager のエラー",
+        "ko": "Container Manager 오류",
+        "de": "Container Manager-Fehler",
+        "fr": "Erreur de Container Manager",
+        "es": "Error de Container Manager",
+        "it": "Errore di Container Manager"
+    },
+    "compose.diagnosis.tls_trust": {
+        "en": "The registry certificate could not be verified. Check the NAS date and time. Ask your network administrator to configure trusted certificates for Container Manager. Alternatively, ask them to let this registry bypass network certificate checks.",
+        "zh-TW": "無法驗證登錄站憑證。請檢查 NAS 日期與時間。若公司網路會攔查加密連線，請網管協助。可為 Container Manager 設定信任憑證，或讓登錄站略過攔查。",
+        "zh-CN": "无法验证镜像仓库证书。请检查 NAS 日期和时间。如果公司网络会检查加密连接，请联系网络管理员。可为 Container Manager 配置信任证书，或让镜像仓库绕过此类检查。",
+        "ja": "レジストリの証明書を検証できません。NAS の日付と時刻を確認してください。Container Manager で信頼する証明書の設定をネットワーク管理者に依頼してください。または、このレジストリをネットワークの証明書検査から除外してもらってください。",
+        "ko": "레지스트리 인증서를 확인할 수 없습니다. NAS 날짜와 시간을 확인하십시오. 네트워크 관리자에게 Container Manager의 신뢰할 수 있는 인증서 설정을 요청하십시오. 또는 이 레지스트리를 네트워크 인증서 검사에서 제외하도록 요청하십시오.",
+        "de": "Das Zertifikat der Registry konnte nicht geprüft werden. Prüfen Sie Datum und Uhrzeit des NAS. Bitten Sie Ihre Netzwerkadministration, vertrauenswürdige Zertifikate für Container Manager einzurichten. Alternativ kann sie diese Registry von der Zertifikatsprüfung im Netzwerk ausnehmen.",
+        "fr": "Le certificat du registre ne peut pas être vérifié. Vérifiez la date et l’heure du NAS. Demandez à votre administrateur réseau de configurer les certificats de confiance pour Container Manager. Il peut aussi exclure ce registre du contrôle des certificats sur le réseau.",
+        "es": "No se pudo verificar el certificado del registro. Compruebe la fecha y la hora del NAS. Solicite a su administrador de red que configure certificados de confianza para Container Manager. Como alternativa, puede excluir este registro de la comprobación de certificados de la red.",
+        "it": "Impossibile verificare il certificato del registro. Controllare la data e l’ora del NAS. Chiedere all’amministratore di rete di configurare i certificati attendibili per Container Manager. In alternativa, chiedere di escludere questo registro dai controlli dei certificati di rete."
+    },
+    "compose.diagnosis.unreachable": {
+        "en": "Cannot reach the registry. Check the NAS network, firewall and Container Manager proxy settings.",
+        "zh-TW": "無法連線至登錄站。檢查 NAS 網路、防火牆及 Container Manager 的代理伺服器設定。",
+        "zh-CN": "无法连接镜像仓库。检查 NAS 网络、防火墙及 Container Manager 的代理服务器设置。",
+        "ja": "レジストリに接続できません。NAS のネットワーク、ファイアウォール、Container Manager のプロキシ設定を確認してください。",
+        "ko": "레지스트리에 연결할 수 없습니다. NAS 네트워크, 방화벽 및 Container Manager 프록시 설정을 확인하십시오.",
+        "de": "Die Registry ist nicht erreichbar. Prüfen Sie Netzwerk, Firewall und die Proxy-Einstellungen von Container Manager.",
+        "fr": "Le registre est inaccessible. Vérifiez le réseau du NAS, le pare-feu et les paramètres de proxy de Container Manager.",
+        "es": "No se puede acceder al registro. Compruebe la red del NAS, el cortafuegos y la configuración de proxy de Container Manager.",
+        "it": "Impossibile raggiungere il registro. Controllare la rete del NAS, il firewall e le impostazioni proxy di Container Manager."
+    },
+    "compose.diagnosis.dns": {
+        "en": "The registry name could not be resolved. Check the NAS DNS settings.",
+        "zh-TW": "無法解析登錄站名稱。檢查 NAS 的 DNS 設定。",
+        "zh-CN": "无法解析镜像仓库名称。检查 NAS 的 DNS 设置。",
+        "ja": "レジストリ名を解決できません。NAS の DNS 設定を確認してください。",
+        "ko": "레지스트리 이름을 확인할 수 없습니다. NAS DNS 설정을 확인하십시오.",
+        "de": "Der Name der Registry konnte nicht aufgelöst werden. Prüfen Sie die DNS-Einstellungen des NAS.",
+        "fr": "Le nom du registre ne peut pas être résolu. Vérifiez les paramètres DNS du NAS.",
+        "es": "No se pudo resolver el nombre del registro. Compruebe la configuración DNS del NAS.",
+        "it": "Impossibile risolvere il nome del registro. Controllare le impostazioni DNS del NAS."
+    },
+    "compose.diagnosis.rate_limit": {
+        "en": "The registry download limit was reached. Wait before trying again. You can also ask an administrator to check registry sign-in.",
+        "zh-TW": "已達登錄站下載上限。請稍後再試，也可請管理員檢查登錄站登入設定。",
+        "zh-CN": "已达到镜像仓库下载上限。请稍后再试，也可请管理员检查镜像仓库登录设置。",
+        "ja": "レジストリのダウンロード制限に達しました。しばらく待つか、管理者にレジストリのサインイン設定の確認を依頼してください。",
+        "ko": "레지스트리 다운로드 한도에 도달했습니다. 기다리거나 관리자에게 레지스트리 로그인 설정 확인을 요청하십시오.",
+        "de": "Das Downloadlimit der Registry wurde erreicht. Warten Sie oder bitten Sie einen Administrator, die Anmeldung bei der Registry zu prüfen.",
+        "fr": "La limite de téléchargement du registre est atteinte. Patientez ou demandez à un administrateur de vérifier la connexion au registre.",
+        "es": "Se alcanzó el límite de descargas del registro. Espere o solicite a un administrador que compruebe el inicio de sesión en el registro.",
+        "it": "È stato raggiunto il limite di download del registro. Attendere o chiedere a un amministratore di controllare l’accesso al registro."
+    },
+    "compose.diagnosis.disk_full": {
+        "en": "There is not enough storage for the image. Free space on Container Manager's storage volume.",
+        "zh-TW": "儲存空間不足，無法下載映像。請釋出 Container Manager 儲存磁碟區的空間。",
+        "zh-CN": "存储空间不足，无法下载映像。请释放 Container Manager 存储卷的空间。",
+        "ja": "イメージ用の空き容量が不足しています。Container Manager のストレージボリュームの空き容量を増やしてください。",
+        "ko": "이미지를 위한 저장 공간이 부족합니다. Container Manager 저장소 볼륨의 공간을 확보하십시오.",
+        "de": "Für das Image ist nicht genug Speicherplatz verfügbar. Geben Sie Speicherplatz auf dem Speichervolume von Container Manager frei.",
+        "fr": "L’espace de stockage est insuffisant pour l’image. Libérez de l’espace sur le volume de stockage de Container Manager.",
+        "es": "No hay espacio de almacenamiento suficiente para la imagen. Libere espacio en el volumen de almacenamiento de Container Manager.",
+        "it": "Lo spazio di archiviazione per l’immagine non è sufficiente. Liberare spazio sul volume di archiviazione di Container Manager."
+    },
+    "compose.diagnosis.not_found": {
+        "en": "The required image version is unavailable. Check for an App update or contact its publisher.",
+        "zh-TW": "所需映像版本無法取得。檢查 App 更新或聯絡發佈者。",
+        "zh-CN": "无法获取所需映像版本。检查应用更新或联系发布者。",
+        "ja": "必要なイメージバージョンを取得できません。アプリの更新を確認するか、公開元に問い合わせてください。",
+        "ko": "필요한 이미지 버전을 사용할 수 없습니다. 앱 업데이트를 확인하거나 게시자에게 문의하십시오.",
+        "de": "Die erforderliche Image-Version ist nicht verfügbar. Prüfen Sie auf App-Updates oder wenden Sie sich an den Herausgeber.",
+        "fr": "La version d’image requise est indisponible. Recherchez une mise à jour de l’application ou contactez son éditeur.",
+        "es": "La versión de imagen requerida no está disponible. Busque una actualización de la aplicación o contacte con su editor.",
+        "it": "La versione dell’immagine richiesta non è disponibile. Verificare gli aggiornamenti dell’app o contattare l’editore."
+    },
+    "compose.diagnosis.denied": {
+        "en": "The registry denied access. Ask an administrator to check registry sign-in and image permissions.",
+        "zh-TW": "登錄站拒絕存取。請管理員檢查登錄站登入設定及映像權限。",
+        "zh-CN": "镜像仓库拒绝访问。请管理员检查镜像仓库登录设置及映像权限。",
+        "ja": "レジストリにアクセスを拒否されました。管理者にレジストリのサインイン設定とイメージの権限の確認を依頼してください。",
+        "ko": "레지스트리가 접근을 거부했습니다. 관리자에게 레지스트리 로그인 설정과 이미지 권한 확인을 요청하십시오.",
+        "de": "Die Registry hat den Zugriff verweigert. Bitten Sie einen Administrator, die Anmeldung und die Image-Berechtigungen zu prüfen.",
+        "fr": "Le registre a refusé l’accès. Demandez à un administrateur de vérifier la connexion au registre et les autorisations de l’image.",
+        "es": "El registro denegó el acceso. Solicite a un administrador que compruebe el inicio de sesión y los permisos de la imagen.",
+        "it": "Il registro ha negato l’accesso. Chiedere a un amministratore di controllare l’accesso al registro e le autorizzazioni dell’immagine."
+    },
+    "compose.diagnosis.unknown": {
+        "en": "The check could not determine the cause. Open Container Manager for details or contact the App publisher.",
+        "zh-TW": "檢查無法判斷原因。開啟 Container Manager 查看詳細資訊，或聯絡 App 發佈者。",
+        "zh-CN": "检查无法确定原因。打开 Container Manager 查看详细信息，或联系应用发布者。",
+        "ja": "確認では原因を特定できませんでした。Container Manager で詳細を確認するか、アプリの公開元に問い合わせてください。",
+        "ko": "확인으로 원인을 파악할 수 없습니다. Container Manager에서 세부 정보를 확인하거나 앱 게시자에게 문의하십시오.",
+        "de": "Die Prüfung konnte die Ursache nicht ermitteln. Öffnen Sie Container Manager für Details oder wenden Sie sich an den App-Herausgeber.",
+        "fr": "La vérification ne permet pas de déterminer la cause. Ouvrez Container Manager pour plus de détails ou contactez l’éditeur de l’application.",
+        "es": "La comprobación no pudo determinar la causa. Abra Container Manager para ver los detalles o contacte con el editor de la aplicación.",
+        "it": "La verifica non ha potuto determinare la causa. Aprire Container Manager per i dettagli o contattare l’editore dell’app."
+    },
+    "compose.diagnosis.repair": {
+        "en": "After fixing the cause, use Package Center \"Repair\". The system will reinstall the package and download missing images.",
+        "zh-TW": "修正後，請在套件中心按「修復」，系統會重新安裝並下載缺少的映像。",
+        "zh-CN": "修正后，请在套件中心点击“修复”，系统会重新安装并下载缺少的映像。",
+        "ja": "原因を解消してから、パッケージセンターで「修復」を実行してください。システムがパッケージを再インストールし、不足しているイメージをダウンロードします。",
+        "ko": "원인을 해결한 후 패키지 센터에서 \"복구\"를 선택하십시오. 시스템이 패키지를 다시 설치하고 누락된 이미지를 다운로드합니다.",
+        "de": "Beheben Sie die Ursache und wählen Sie im Paket-Zentrum „Reparieren“. Das System installiert das Paket erneut und lädt fehlende Images herunter.",
+        "fr": "Corrigez la cause, puis sélectionnez « Réparer » dans le Centre de paquets. Le système réinstallera le paquet et téléchargera les images manquantes.",
+        "es": "Corrija la causa y seleccione \"Reparar\" en el Centro de paquetes. El sistema reinstalará el paquete y descargará las imágenes que faltan.",
+        "it": "Correggere la causa e selezionare «Ripara» nel Centro pacchetti. Il sistema reinstallerà il pacchetto e scaricherà le immagini mancanti."
+    },
+    "compose.diagnosis.error_code": {
+        "en": "(Error code: {code})",
+        "zh-TW": "（錯誤碼：{code}）",
+        "zh-CN": "（错误代码：{code}）",
+        "ja": "（エラーコード：{code}）",
+        "ko": "(오류 코드: {code})",
+        "de": "(Fehlercode: {code})",
+        "fr": "(Code d’erreur : {code})",
+        "es": "(Código de error: {code})",
+        "it": "(Codice errore: {code})"
+    },
     "delegate.preselection": {
         en: "Pre-select the shared folder for background saves. Confirm this selection with your administrator password when first enabling background access in the app. This does not grant the package account access to the share.",
         "zh-TW": "預選背景存檔使用的共用資料夾。首次在 App 啟用背景存取時，以管理員密碼確認這個選項。這不會授予套件帳號共用資料夾權限。",

package/dist/runtime/executor-digests.json

@@ -31,5 +31,16 @@
             "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.17.4": {
+        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
+        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
+        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
+        "lifecycle": {
+            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
+            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
+            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
+        },
+        "goToolchain": "go1.26.9"
     }
 }

package/dist/standalone/compose-errors.js

@@ -1,5 +1,15 @@
 /** SDK planner errors accepted at this versioned tool boundary. */
 export const COMPOSE_ERRORS = {
+    COMPOSE_STARTUP_INVALID: {
+        code: "COMPOSE_STARTUP_INVALID",
+        description: "The container startup budget is invalid.",
+        suggestion: "Set compose.startup_timeout_seconds to an integer from 2 to 900 seconds; the default is 120. Read the same SYNOPKGLAND_STARTUP_BUDGET_SECONDS in the App bootstrap adapter.",
+    },
+    COMPOSE_STARTUP_TIMEOUT: {
+        code: "COMPOSE_STARTUP_TIMEOUT",
+        description: "Container readiness exhausted its declared startup budget.",
+        suggestion: "Inspect the safe phase code in daemon/daemon.log and upstream migration/bootstrap health. Declare a sufficient bounded startup_timeout_seconds and rebuild; keep ingress closed until ready.",
+    },
     COMPOSE_STORAGE_INIT_INVALID: {
         code: "COMPOSE_STORAGE_INIT_INVALID",
         description: "The container storage initialization declaration is invalid.",

package/dist/standalone/compose.d.ts

@@ -2,6 +2,7 @@ import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import { type Daemon } from "./daemon.js";
 import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface ComposePlan {
+    startup_timeout_seconds?: number;
     ingress?: {
         address: string;
         subnet: string;
@@ -68,7 +69,7 @@ export interface ComposeApp {
     document: Record<string, any>;
     plan: ComposePlan;
 }
-export declare const COMPOSE_FIELDS: readonly ["resource_prefix", "files", "env_files", "profiles", "web", "data", "shares", "network", "services", "helpers", "sdk"];
+export declare const COMPOSE_FIELDS: readonly ["startup_timeout_seconds", "resource_prefix", "files", "env_files", "profiles", "web", "data", "shares", "network", "services", "helpers", "sdk"];
 export declare function readComposeApp(value: unknown, root: string, arches: NativeArchFamily[], fail: (e: StandaloneError) => void, context?: {
     package?: string;
     sdk?: string;

package/dist/standalone/compose.js

@@ -1,3 +1,4 @@
+import { composeDiagnosisMessages, renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
 import { COMPOSE_ERRORS } from "./compose-errors.js";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -10,6 +11,7 @@ import { goChildEnv } from "../runtime/go-env.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { readDaemon } from "./daemon.js";
 export const COMPOSE_FIELDS = [
+    "startup_timeout_seconds",
     "resource_prefix",
     "files",
     "env_files",
@@ -69,6 +71,10 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
     if (value.sdk !== undefined &&
         (typeof value.sdk !== "string" || !/^\d+\.\d+\.\d+$/.test(value.sdk)))
         return invalid("compose.sdk must name the matching SDK release.", "SDK_COMPOSE_UNSUPPORTED");
+    if (value.startup_timeout_seconds !== undefined &&
+        (!Number.isInteger(value.startup_timeout_seconds) ||
+            value.startup_timeout_seconds < 2 || value.startup_timeout_seconds > 900))
+        return invalid("compose.startup_timeout_seconds must be an integer from 2 to 900 seconds (default 120).", "COMPOSE_STARTUP_INVALID");
     const sdk = typeof value.sdk === "string" ? value.sdk : (context.sdk ?? templateSdkVersion());
     let targets = {};
     if (value.helpers !== undefined) {
@@ -107,6 +113,9 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
         }
         if (result.status !== 0 || plan.error)
             throw new Error(plan.error ?? "[SDK_COMPOSE_FAILED] SDK planner failed.");
+        if (value.startup_timeout_seconds !== undefined &&
+            plan.startup_timeout_seconds !== value.startup_timeout_seconds)
+            throw new Error("[SDK_COMPOSE_UNSUPPORTED] This SDK does not implement the declared startup budget; use the matching SDK/CLI release.");
         const document = parse(plan.effective);
         const web = value.web;
         return {
@@ -141,7 +150,7 @@ export function composeDaemon(m) {
         args: ["run"],
         targets: m.compose.targets,
         env: {},
-        timeouts: { start: 120, stop: 30, status: 5, uninstall: 60 },
+        timeouts: { start: m.compose.plan.startup_timeout_seconds ?? 120, stop: 30, status: 5, uninstall: 60 },
     };
 }
 export function composeNetwork(m) {
@@ -187,6 +196,7 @@ export function writeComposePayload(c, root, target, gateway) {
         "compose.lock.json": JSON.stringify(c.plan.lock, null, 2) + "\n",
         "request.json": JSON.stringify({ declaration: c.declaration, sdk: c.sdk, gateway }, null, 2) + "\n",
         "images.json": JSON.stringify(c.plan.image_proofs ?? {}, null, 2) + "\n",
+        "diagnosis-messages.json": JSON.stringify(composeDiagnosisMessages(), null, 2) + "\n",
     }))
         writeFileSync(join(target, name), content, { mode: 0o600 });
 }
@@ -195,7 +205,7 @@ export function renderComposeInstall(pkg) {
     return `#!/bin/sh
 set -eu
 "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" preflight || exit $?
-exec "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" prepare --project "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose" --package '${pkg}'
+${renderComposeDiagnosis("\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose", "preinst")}exec "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" prepare --project "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose" --package '${pkg}'
 `;
 }
 /** The same SDK entry point supplies the package-account install materializer. */

package/dist/standalone/lifecycle.js

@@ -1,3 +1,4 @@
+import { renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
 import { composeDaemon, renderComposeInstall } from "./compose.js";
 import { renderBackgroundControl, renderBackgroundWorkerStart, renderBackgroundWorkerStop, renderUserManagerRecovery, backgroundUnitName, } from "./background.js";
 import { renderPackagePostuninst } from "../build-spk/native-lifecycle.js";
@@ -29,7 +30,13 @@ export function renderStandaloneScript(name, manifest) {
             !manifest.compose.plan.mounts_blocked
             ? `"/var/packages/${manifest.package}/target/compose/control" remember-ingress --project "/var/packages/${manifest.package}/target/compose" --package '${manifest.package}' || exit $?\n`
             : "";
-        const ledger = preflight + remember +
+        const project = `\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/compose`;
+        const diagnosis = ["postinst", "postupgrade"].includes(name)
+            ? renderComposeDiagnosis(project, name)
+            : name === "start-stop-status"
+                ? `if [ "$1" = prestart ]; then\n  ${renderComposeDiagnosis(project, "prestart")}fi\n`
+                : "";
+        const ledger = diagnosis + preflight + remember +
             (manifest.identityGateway && !manifest.compose.plan.mounts_blocked
                 ? name === "start-stop-status"
                     ? `if [ "$1" = restart ]; then\n  "$0" stop || exit $?\n  exec "$0" start\nfi\nif [ "$1" = start ]; then\n  ${control} acquire ${paths} || exit $?\nelif [ "$1" = stop ]; then\n  ${control} release ${paths} || exit $?\nfi\n`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "0.17.5",
+    "@synopackageland/templates": "0.17.6",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/reference/compose.md

@@ -35,6 +35,28 @@ and `identity_gateway` for headless projects. Optional `compose.helpers` names
 architecture-specific native payloads for token/account adapters. All lifecycle
 scripts run as the package account; containers are managed by Container Manager.
 
+## Startup budget
+
+Set `compose.startup_timeout_seconds: 600` for a slow cold start or migration.
+Omitting it uses 120 seconds; only integers from 2 through 900 are accepted.
+Use a matching SDK that implements the field and rebuild the App; older planners
+are rejected for explicit budgets. The SDK plan drives generated daemon start
+and supplies every container with `SYNOPKGLAND_STARTUP_BUDGET_SECONDS`, overriding
+upstream and service-policy values for that SDK-owned key.
+
+Custom bootstrap adapters must read that environment value once and use one
+deadline across all bootstrap phases; an existing hardcoded adapter timer does
+not change automatically. Keep the health endpoint unready until setup/migration
+and any serving restart finish. Do not log credentials, raw API errors or bodies.
+
+The gateway starts after readiness, so ingress remains closed while waiting.
+The supervisor reserves five extra seconds for handoff/probe completion/process
+stability. Timeout returns `COMPOSE_STARTUP_TIMEOUT` plus a safe last `phase` code
+in the start result and `daemon/daemon.log`. Stop/uninstall limits are independent.
+The budget begins after the native Container Manager worker returns; it does not
+extend image pulls, native worker acquisition or Package Center deadlines. Verify
+the installed DSM unit and full fresh-install lifecycle on the target NAS.
+
 ## Planning and artifacts
 
 The pinned compose-go reference loader merges ordered files, env files and