@synopackageland/cli 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -1,17 +1,30 @@
 # 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.
+- Record SDK 0.17.3 executor and lifecycle digests; all six payloads are unchanged from 0.17.1.
+- Keep the “User password” wording in all nine locales and package the generated native SDK version identifiers.
+
 ## 0.17.2 (2026-10-19)
 
 - Pin templates with matching frontend and native SDK versions.
 - Record the verified SDK 0.17.1 executor and lifecycle payload digests.
 - Rename password labels and approval instructions to “User password” across all nine locales.
-- 對齊前後端 SDK 版本，並記錄 SDK 0.17.1 的 executor 與 lifecycle digest。
 
-## 0.17.1 (unreleased)
+## 0.17.1 (2026-10-19)
 
 - Remove environment-specific release notes and source comments from distributed content, including generated DSM window scripts.
 - Prepare npm releases from a clean package directory without local archive references.
-- 清理發佈內容中的環境識別敘述；以乾淨套件目錄準備 npm 發佈。
 
 ## 0.17.0 (2026-10-19)
 

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/assets/init-compose.md

@@ -22,7 +22,7 @@ Application Portal. Headless Apps omit compose.web and have no launcher.
 Compose ctl is unsupported.
 
 Use supported upstream config files, environment, argv or reverse proxy for
-login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.17.0 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
+login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.17.3 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
 Containers use the package account and a dedicated bridge; they do not inherit
 an interactive user's NAS ACL. Do not use root/chown during any App lifecycle
 phase. Preserve licenses and dependency/source provenance. Read the CLI skill

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/init-upstream.js

@@ -58,7 +58,7 @@ Commit the scaffold, then run bash synology/upgrade.sh <upstream-tag> <build-num
 
 ${official ? 'Default: use the upstream official image. upgrade.sh updates its release tag and resolves an OCI index/manifest digest through synopkgland images pin, writing only synology/compose.image.yaml. Container Manager downloads that pinned official image at install. Configure upstream-recipe.json repository/service and imageTag: tag (exact upstream tag) or version (strip v only when upstream image naming requires it). Review multi-architecture support and upstream source/license correspondence. The SELECT_UPSTREAM_TAG placeholder must be replaced by a successful upgrade before check/build.' : 'Native App: implement build-source.sh as the native payload hook; it deliberately fails until implemented. Stage official release binaries pinned by SHA-256 (the OpenList route), or compile the merged source with a source build hook. Verify the release digest before staging architecture-specific daemon.targets; keep the SDK management shell separate.'}
 
-Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.17.0 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
+Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.17.3 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
 `;
     writeFileSync(join(packaging, 'AGENTS.md'), readFileSync(join(packaging, 'AGENTS.md'), 'utf8') + guidance);
 }

package/dist/runtime/executor-digests.json

@@ -20,5 +20,27 @@
             "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.17.3": {
+        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
+        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
+        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
+        "lifecycle": {
+            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
+            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
+            "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.2",
+  "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.3",
+    "@synopackageland/templates": "0.17.6",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
-For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.0 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
+For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
 Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. For all Compose work, read [reference/compose.md](reference/compose.md): schema-2 upstream files, generated override, SDK planner, fixed package identity and current DSM blockers. Containers do not inherit a signed-in user's File Station ACL. Existing Shared Folder mounts are blocked until official protected ACL/project control is verified.
 

package/skills/reference/compose.md

@@ -23,7 +23,7 @@ compose:
   network: {egress: isolated}
   # Private package binds are rejected by DSM build; keep compatible upstream named volumes.
 identity_gateway:
-  sdk: 0.17.0
+  sdk: 0.17.3
   mode: none
   access: dsm-users
   listen: {http: 28000}
@@ -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
@@ -151,7 +173,7 @@ declared availability readiness, LAN isolation/egress, protected grant lifecycle
 ACLs, two-user visibility and clean install/upgrade/reboot/stop/uninstall before
 calling the package supported on a NAS. No NAS is accessed by the build gate.
 
-The unified Compose contract uses SDK 0.17.0 and templates 0.17.1 with CLI 0.17.0. Use the published, matching versions together; the legacy packaging route and bridge publish mode are removed.
+The unified Compose contract uses SDK 0.17.3 and templates 0.17.5 with CLI 0.17.3. Use the published, matching versions together; the legacy packaging route and bridge publish mode are removed.
 
 Primary override files, and each included override set, must share a directory. Cross-directory override bases are rejected before loader I/O. Included implicit .env files are confined, inventoried and preserved; symlinks are rejected.
 

package/skills/reference/create.md

@@ -40,8 +40,8 @@ rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected exec
 backend 寫 `runtime: python|node|rust`（`runtime: go` 等同 `kind: go`）。CGI 是 SDK 的 Go runtime（`bridge/cmd/runtime`），它驗證 DSM session、entry 與 `permissions.json` 後，以套件帳號（不是 root）每個請求啟動一次 App。App 放在 ui 以外的目錄，打包成 `target/app/`，build 寫入 `bridge.json`（spec/bridge/v1）並把它與 `permissions.json` 的 sha256 編進 runtime。
 
 ```yaml
-backend: {runtime: python, dir: app, entry: main.py, sdk: 0.17.0}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.17.0, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.17.3}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.17.3, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 

package/skills/reference/upstream-fork.md

@@ -104,7 +104,7 @@ upstream mechanisms in order:
    If manual App login is still necessary, label bootstrap incomplete. Verify
    subsequent DSM entry, restart and upgrade all retain password-free access,
    while anonymous/nonadmin requests and direct upstream ports remain blocked.
-3. **Existing SDK token adapter**: SDK **0.17.0** supports `mode: token`, with
+3. **Existing SDK token adapter**: SDK **0.17.3** supports `mode: token`, with
    `access: dsm-admins` and `entry: admin-only`. OpenList uses its unmodified
    upstream `admin token` CLI while the server is stopped to obtain the native
    administrator API token. The package stores it in a package-private **0600**
@@ -142,7 +142,7 @@ is undecided. Never copy credentials into generated projects.
 
 | Prototype | Reusable lesson and remaining boundary |
 | --- | --- |
-| OpenList | Official release binary pinned by SHA-256, `/ping` and SDK 0.17.0 server-side token adapter; shared upstream admin, restart after token reset, native WebDAV credentials. Share selection does not grant package ACL/register Local storage. |
+| OpenList | Official release binary pinned by SHA-256, `/ping` and SDK 0.17.3 server-side token adapter; shared upstream admin, restart after token reset, native WebDAV credentials. Share selection does not grant package ACL/register Local storage. |
 | FreshRSS | Official image, package-UID Apache/config adapter in `synology/`, explicit health; supported proxy authentication with fixed admin mapping and header clearing. |
 | Uptime Kuma | Official image, writable-path adapter, nonredirecting health and `disableAuth` after first bootstrap; WebSocket expiry/revocation need separate tests. |