@synopackageland/cli 0.17.3 → 0.17.5

package/dist/standalone/native-gateway.js

@@ -0,0 +1,115 @@
+import { isDsmAtLeast, PORTAL_MIN_DSM } from '../build-spk/dsm-version.js';
+export const NATIVE_GATEWAY_CONFIG = 'sso/native-nginx.conf';
+// Earlier SDK releases do not understand native_ingress. Keep their JSON ABI
+// and put an explanation in front of their existing direct-port launcher.
+export function nativeGatewaySdk(sdk) {
+    const [major, minor, patch] = sdk.split('.').map(Number);
+    return major > 0 || minor > 17 || minor === 17 && patch >= 5;
+}
+export function nativeGatewaySupported(m) {
+    return Boolean(m.identityGateway && nativeGatewaySdk(m.identityGateway.sdk)
+        && m.os_min_ver && isDsmAtLeast(m.os_min_ver, PORTAL_MIN_DSM));
+}
+export function gatewayEntryPath(m) {
+    return `/webman/3rdparty/${m.package}/sso/open.${m.identityGateway && !nativeGatewaySdk(m.identityGateway.sdk) ? 'html' : 'cgi'}`;
+}
+export function legacyGatewayNotice() {
+    return '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src \'none\'; frame-ancestors \'none\'"><title>Direct App connection</title><p>DSM-managed HTTPS is unavailable for this App. The direct connection may show a certificate warning or use unencrypted HTTP.</p><a href="open.cgi">Continue to the direct connection</a></html>\n';
+}
+export function nativeGatewayResource(m) {
+    if (!nativeGatewaySupported(m))
+        return undefined;
+    const g = m.identityGateway, https = g.listen.https ?? g.listen.http;
+    const ports = [https, ...(g.listen.http && g.listen.http !== https ? [g.listen.http] : [])];
+    return { 'nginx-static-config': { enable: [{ type: 'server', relpath: NATIVE_GATEWAY_CONFIG,
+                    ports: ports.map(port => ({ port, protocol: 'tcp', schema: port === https ? 'https' : 'http' })) }] } };
+}
+export function renderNativeGatewayConfig(m) {
+    if (!nativeGatewaySupported(m))
+        return '';
+    const g = m.identityGateway, port = g.listen.https ?? g.listen.http;
+    const state = `/var/packages/${m.package}/var/sso`;
+    // Public ssl_certificate is deliberately inherited from DSM's http context.
+    // Only nginx's master reads the package's private upstream key. No DSM key
+    // is read or copied by the package, and no secret appears in this config.
+    return `server {
+    listen ${port} ssl;
+    listen [::]:${port} ssl;
+    server_name _;
+    client_max_body_size 0;
+    location / {
+        proxy_pass https://unix:/tmp/synopkgland-gateway-${m.package}.sock:;
+        proxy_http_version 1.1;
+        proxy_ssl_verify on;
+        proxy_ssl_verify_depth 1;
+        proxy_ssl_server_name on;
+        proxy_ssl_name gateway.invalid;
+        proxy_ssl_trusted_certificate ${state}/native-cert.pem;
+        proxy_ssl_certificate ${state}/native-cert.pem;
+        proxy_ssl_certificate_key ${state}/native-key.pem;
+        proxy_set_header Host $http_host;
+        proxy_set_header X-Synopkgland-Client-IP $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $http_connection;
+        proxy_request_buffering off;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+    }
+}
+${g.listen.http && g.listen.http !== port ? `server {
+    listen ${g.listen.http};
+    listen [::]:${g.listen.http};
+    server_name _;
+    return 308 https://$host:${port}$request_uri;
+}
+` : ''}`;
+}
+/** Runs after DSM creates pkgvar, before package start activates the nginx resource. */
+export function renderNativeGatewayPrepare(m) {
+    if (!nativeGatewaySupported(m))
+        return '';
+    return `synopkgland_native_keys() (
+  set -eu
+  umask 077
+  v="\${SYNOPKG_PKGVAR:-/var/packages/${m.package}/var}/sso"
+  if [ -L "$v" ]; then echo 'Native HTTPS state must not be a symlink.' >&2; exit 1; fi
+  mkdir -p "$v"
+  if [ "$(stat -c %a "$v")" != 700 ]; then echo 'Native HTTPS state must have mode 0700.' >&2; exit 1; fi
+  c="$v/native-cert.pem"; k="$v/native-key.pem"
+  if [ -e "$c" ] || [ -L "$c" ] || [ -e "$k" ] || [ -L "$k" ]; then
+    for f in "$c" "$k"; do
+      if [ -L "$f" ] || [ ! -f "$f" ] || [ "$(stat -c %a "$f")" != 600 ]; then
+        echo 'Native HTTPS requires a complete private keypair with mode 0600.' >&2; exit 1
+      fi
+    done
+    /usr/bin/openssl x509 -in "$c" -noout -checkend 0 >/dev/null || exit 1
+    cp=$(/usr/bin/openssl x509 -in "$c" -pubkey -noout | /usr/bin/openssl sha256)
+    kp=$(/usr/bin/openssl pkey -in "$k" -pubout | /usr/bin/openssl sha256)
+    [ "$cp" = "$kp" ] || { echo 'Native HTTPS keypair does not match.' >&2; exit 1; }
+    exit 0
+  fi
+  t=$(mktemp -d "$v/.native-tls.XXXXXX")
+  trap 'rm -rf "$t"' EXIT HUP INT TERM
+  cat > "$t/openssl.cnf" <<'NATIVE_TLS_CONFIG'
+[req]
+distinguished_name=subject
+x509_extensions=extensions
+prompt=no
+[subject]
+CN=gateway.invalid
+[extensions]
+basicConstraints=critical,CA:TRUE
+keyUsage=critical,digitalSignature,keyEncipherment,keyCertSign
+extendedKeyUsage=serverAuth,clientAuth
+subjectAltName=DNS:gateway.invalid
+NATIVE_TLS_CONFIG
+  /usr/bin/openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -config "$t/openssl.cnf" -keyout "$t/key.pem" -out "$t/cert.pem" >/dev/null 2>&1 || {
+    echo 'Could not prepare the private native HTTPS connection.' >&2; exit 1;
+  }
+  chmod 600 "$t/key.pem" "$t/cert.pem"
+  mv "$t/key.pem" "$k"
+  mv "$t/cert.pem" "$c"
+)
+synopkgland_native_keys || exit $?
+`;
+}

package/dist/standalone/resource.d.ts

@@ -2,6 +2,7 @@ import type { ComposeApp } from "./compose.js";
 import type { Capabilities } from "./manifest.js";
 import { type SharedFolder } from "./shared-folder.js";
 import { type PortalPackage } from "../portal/package.js";
+import { type NativeGatewayPlan } from './native-gateway.js';
 /**
  * `conf/resource` for a native package: only DSM's official `data-share`,
  * `systemd-user-unit` and `web-config` workers, in a fixed key order.
@@ -9,6 +10,8 @@ import { type PortalPackage } from "../portal/package.js";
  */
 export declare function renderStandaloneResource(m: {
     package: string;
+    os_min_ver?: string;
+    identityGateway?: NativeGatewayPlan;
     capabilities: Capabilities;
     compose?: ComposeApp;
     sharedFolder?: SharedFolder;

package/dist/standalone/resource.js

@@ -1,6 +1,7 @@
 import { renderDockerProjectResource } from "../build-spk/resource-worker.js";
 import { sharedFolderResource } from "./shared-folder.js";
 import { portalResource } from "../portal/package.js";
+import { nativeGatewayResource } from './native-gateway.js';
 /**
  * `conf/resource` for a native package: only DSM's official `data-share`,
  * `systemd-user-unit` and `web-config` workers, in a fixed key order.
@@ -8,13 +9,14 @@ import { portalResource } from "../portal/package.js";
  */
 export function renderStandaloneResource(m, portal) {
     const dataShare = m.sharedFolder && sharedFolderResource(m.package, m.sharedFolder);
+    const webConfig = { ...(portal ? portalResource()['web-config'] : {}), ...nativeGatewayResource(m) };
     const resource = {
         ...(m.compose && !m.compose.plan.mounts_blocked
             ? renderDockerProjectResource(m.package, "compose", false, m.compose.plan.project_name)
             : {}),
         ...(dataShare ? { "data-share": dataShare } : {}),
         ...(m.capabilities.jobs ? { "systemd-user-unit": {} } : {}),
-        ...(portal ? portalResource() : {}),
+        ...(Object.keys(webConfig).length ? { 'web-config': webConfig } : {}),
     };
     return Object.keys(resource).length > 0
         ? JSON.stringify(resource)

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { nativeGatewaySupported, nativeGatewaySdk, renderNativeGatewayConfig, NATIVE_GATEWAY_CONFIG, legacyGatewayNotice, gatewayEntryPath } from './native-gateway.js';
 import { portalInfoFields } from "../portal/info.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { resolvedSdkLaunch } from "../contract/app-launch.js";
@@ -116,6 +117,10 @@ export async function assembleStandaloneSpk(options) {
                 chmodSync(target, EXEC_MODE);
             }
             writeFile(join(staging, "package", GATEWAY_CONFIG_PATH), identityGatewayConfig(manifest));
+            if (nativeGatewaySupported(manifest))
+                writeFile(join(staging, 'package', NATIVE_GATEWAY_CONFIG), renderNativeGatewayConfig(manifest));
+            if (!nativeGatewaySdk(manifest.identityGateway.sdk))
+                writeFile(join(staging, 'package/ui/sso/open.html'), legacyGatewayNotice());
         }
         if (manifest.capabilities.jobs) {
             if (!options.backgroundWorker)
@@ -208,8 +213,11 @@ export async function assembleStandaloneSpk(options) {
             .digest("hex");
         writeFile(join(staging, "sdk-package.json"), JSON.stringify({
             schema: 2,
+            ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
+            ...("timeoutSeconds" in manifest.backend && manifest.backend.timeoutSeconds ? { operationSeconds: manifest.backend.timeoutSeconds } : {}),
             ...(options.apiDescription ? { ctl: { hash: options.apiDescription.sha256, registry: options.apiRegistry } } : {}),
             backend: manifest.backend.kind,
+            ...(nativeGatewaySupported(manifest) ? { native_gateway: { sdk: manifest.identityGateway.sdk, listen: manifest.identityGateway.listen } } : {}),
             launch: resolvedSdkLaunch(manifest),
             capabilities: Object.keys(manifest.capabilities).sort(),
             ...(manifest.compose
@@ -236,7 +244,7 @@ export async function assembleStandaloneSpk(options) {
             writeFile(join(staging, "conf", "resource"), resource);
         if (manifest.capabilities.jobs) {
             mkdirSync(join(staging, BACKGROUND_UNIT_DIR), { recursive: true });
-            writeFile(join(staging, BACKGROUND_UNIT_DIR, backgroundUnitName(manifest.package)), renderBackgroundUnit(manifest.package, isBridgeBackend(manifest.backend) ? BRIDGE_WORKER_ARGS : []));
+            writeFile(join(staging, BACKGROUND_UNIT_DIR, backgroundUnitName(manifest.package)), renderBackgroundUnit(manifest.package, isBridgeBackend(manifest.backend) ? BRIDGE_WORKER_ARGS : [], manifest.daemon?.timeouts.stop ?? manifest.lifecycleTimeouts?.stop ?? 30));
         }
         mkdirSync(join(staging, "scripts"));
         for (const name of LIFECYCLE_SCRIPTS) {
@@ -265,6 +273,7 @@ export async function assembleStandaloneSpk(options) {
                 ? renderSharedFolderUpgradeWizardFiles(manifest.package, folder)
                 : {}),
             ...renderUninstallWizardFiles(manifest.package, "native", {
+                composeData: manifest.compose?.plan.app_data,
                 executor: Boolean(options.executor),
                 portal: Boolean(portal),
                 portalEntry: Boolean(manifest.portal && portalByExecutor(manifest.os_min_ver)),
@@ -324,7 +333,7 @@ export function renderInfo(manifest, arch, checksum, executorDigest) {
         if (manifest.identityGateway)
             fields.push([
                 "adminurl",
-                `/webman/3rdparty/${manifest.package}/sso/open.cgi`,
+                gatewayEntryPath(manifest),
             ]);
     }
     const backend = manifest.backend;
@@ -341,7 +350,9 @@ export function renderInfo(manifest, arch, checksum, executorDigest) {
         if (text?.description)
             fields.push([`description_${DSM_LANGS[locale]}`, text.description]);
     }
-    return portalInfoFields(fields, Boolean(manifest.portal)).map(([key, value]) => `${key}=${quote(value)}\n`).join("");
+    if (nativeGatewaySupported(manifest))
+        fields.push(['startstop_restart_services', 'nginx.service']);
+    return portalInfoFields(fields, Boolean(manifest.portal) || nativeGatewaySupported(manifest)).map(([key, value]) => `${key}=${quote(value)}\n`).join("");
 }
 function copyUiTree(source, target) {
     for (const entry of ["app.js", "app.css"]) {

package/dist/standalone/uninstall-hook.js

@@ -22,6 +22,7 @@ export function renderUninstallHook(manifest) {
     if (!purge)
         return "";
     const pkg = manifest.package;
+    const reserve = Math.min(5, Math.max(1, Math.floor(purge.timeout / 4)));
     const env = [
         "PATH=/usr/bin:/bin", 'HOME="$hook_var"', 'TMPDIR="$hook_var/tmp"',
         ...Object.entries(purge.env).map(([key, value]) => `${key}=${word(value)}`),
@@ -47,7 +48,11 @@ ${manifest.uninstall?.state ? wizardFlag("delete_state", ["pkgwizard_delete_stat
   # DSM's bash logs a failed kill to syslog even with 2>/dev/null, so a
   # finished hook is looked up in /proc wherever there is one.
   hook_running() {
-    if [ -d /proc/self ]; then [ -d "/proc/$hook_pid" ]; else kill -0 "$hook_pid" 2>/dev/null; fi
+    if [ -d /proc/self ]; then
+      [ -r "/proc/$hook_pid/stat" ] || return 1
+      case "$(sed 's/.*) //' "/proc/$hook_pid/stat" 2>/dev/null)" in Z*|X*|'') return 1 ;; esac
+      return 0
+    else kill -0 "$hook_pid" 2>/dev/null; fi
   }
   # A process in /proc whose group is the hook's ("pid (comm) state ppid pgrp ...").
   hook_group_running() {
@@ -62,19 +67,27 @@ ${manifest.uninstall?.state ? wizardFlag("delete_state", ["pkgwizard_delete_stat
       kill -"$1" "$hook_pid"
     fi
   }
-  hook_waited=0
-  while hook_running && [ "$hook_waited" -lt ${purge.timeout} ]; do
-    sleep 1
-    hook_waited=$((hook_waited + 1))
+  hook_now() { if [ -r /proc/uptime ]; then awk '{print int($1)}' /proc/uptime; else date +%s; fi; }
+  hook_until=$(( $(hook_now) + ${purge.timeout} ))
+  hook_work_until=$((hook_until - ${reserve}))
+  while hook_running && [ "$(hook_now)" -lt "$hook_work_until" ]; do
+    sleep 0.1
   done
   hook_failure=
   if hook_running; then
     hook_signal TERM
-    sleep 1
+    hook_grace_until=$((hook_until - 1))
+    while hook_group_running && [ "$(hook_now)" -lt "$hook_grace_until" ]; do sleep 0.1; done
     hook_signal KILL
-    wait "$hook_pid" 2>/dev/null
-    hook_failure="timeout after ${purge.timeout} s"
+    while hook_running && [ "$(hook_now)" -lt "$hook_until" ]; do sleep 0.1; done
+    if hook_running || hook_group_running; then
+      echo cleanup-pending >"$hook_var/uninstall-hook.pending"
+    else
+      wait "$hook_pid" 2>/dev/null
+    fi
+    hook_failure="timeout after ${purge.timeout} s; cleanup may be pending"
   else
+    rm -f "$hook_var/uninstall-hook.pending"
     wait "$hook_pid"
     hook_status=$?
     [ "$hook_status" -eq 0 ] || hook_failure="exit $hook_status"

package/dist/standalone/uninstall.d.ts

@@ -19,7 +19,7 @@ export interface UninstallPurge {
     exec: string;
     args: string[];
     env: Record<string, string>;
-    /** Seconds, 2..120. */
+    /** Seconds, 2..3600. */
     timeout: number;
     /** A root/<name>.sh the executor runs at uninstall, only while its approval is live. */
     root?: string;

package/dist/standalone/uninstall.js

@@ -16,7 +16,7 @@ export function readUninstall(value, context, fail) {
     if (value === undefined)
         return undefined;
     const invalid = () => {
-        fail({ code: "UNINSTALL_INVALID", message: "uninstall accepts only purge {exec, args, env, timeout, root} and state {items: [{key}]}; exec must be a fixed executable inside the package (not in executor/ or root/), and timeout is an integer from 2 to 120 seconds." });
+        fail({ code: "UNINSTALL_INVALID", message: "uninstall accepts only purge {exec, args, env, timeout, root} and state {items: [{key}]}; exec must be a fixed executable inside the package (not in executor/ or root/), and timeout is an integer from 2 to 3600 seconds." });
         return undefined;
     };
     if (!record(value) || Object.keys(value).some(k => !FIELDS.has(k)))
@@ -54,7 +54,7 @@ function readPurge(value, context, fail) {
         || Object.entries(env).some(([k, v]) => !envKey(k) || k.startsWith("SYNOPKGLAND_") || !token(v)))
         return "invalid";
     const timeout = value.timeout ?? 60;
-    if (!Number.isInteger(timeout) || timeout < 2 || timeout > 120)
+    if (!Number.isInteger(timeout) || timeout < 2 || timeout > 3600)
         return "invalid";
     const root = value.root;
     if (root !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "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.8",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/reference/compose.md

@@ -35,6 +35,34 @@ 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.
+Lock waiting, status, readiness, stability and handoff share that deadline; there
+is no extra fixed handoff allowance. The cap is a policy bound, not a measured
+DSM lifecycle limit. `daemon: {timeouts: {stop: 120, status: 15, uninstall: 300}}`
+configures the other lifecycle phases without declaring a daemon payload.
+A transient health failure closes new ingress while the running App gets one
+operation-budget recovery window; authority or generation failures stop at once.
+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
@@ -364,3 +392,28 @@ Do not silently switch networking, add Docker socket access, run an App hook as
 root or delete DSM configuration to claim compatibility.
 
 Compose web health is required before check/build; init has no guessed endpoint or status. Select both `--health-path` and `--health-status`, or edit `compose.web.health`. Readiness does not follow redirects. Static check is not an HTTP or arbitrary-UID/storage preflight. For official-image upstream packaging and DSM login, read [upstream-fork.md](upstream-fork.md).
+
+
+## Named volumes and uninstall
+
+The SDK planner and lock inventory all current project-owned named volumes as
+App data, with exact names. Compose alone never selects an executor or root
+permissions. The package account does not delete named volumes or access Docker.
+
+Before confirmation, the uninstall wizard states that container data volumes
+are kept even when delete-data is selected, and lists the current exact names.
+Only exact `SYNOPKG_PKG_STATUS=UNINSTALL` with an affirmative
+`pkgwizard_remove_additional` (or supported mirror/legacy alias) clears the
+package data/config/home contents the package account can clear. Upgrade, stop,
+unknown status and keep preserve data. Unsafe paths and remnants are reported.
+
+On delete-data uninstall with a nonempty volume inventory, generated postuninst
+appends nine-language native text through `SYNOPKG_TEMP_LOGFILE`, preserving
+existing text. It says plainly the listed volumes were NOT deleted and ends
+with `COMPOSE_DATA_RETAINED`. The list is the current planner/lock inventory,
+not a runtime existence check; volumes retired by older versions may also remain.
+No full-data-deletion success is claimed and no unverified deletion path is given.
+Administrator cleanup procedures, executor-tier Apps and storage redesign are
+out of scope. Final DSM native UI acceptance remains required.
+
+See the SDK's [Compose App data contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/compose-app-data.md).

package/skills/reference/create.md

@@ -113,7 +113,7 @@ root:
     migrate: {}          # 沒有 run、job：只作為 start 步驟
 ```
 
-start、stop 步驟與 `uninstall.purge.root` 都以 root、無 session 執行，只在管理員核准有效時跑；這些程式不能宣告 run 或 job（session 要用時以另一個名稱設定，可指向同一份內容）。start 步驟在新版本第一次啟動、executor 開 socket 並回讀核准任務之後執行，最多 60 秒；執行期間 executor 只回應 `status`（`state: "starting"`），其他請求回可重試的 `EXECUTOR_STARTING`，DSM 視窗的核准會等它結束，狀態讀取則立即回 `executor_starting`、由 SDK 面板自行重試，失敗只寫進 executor log，不擋啟動；同一版本不重跑，程式要能重複執行。結果由 executor `status` 的 `start_step` 讀取（`pending`、`ok`、`failed`，含 exit 與 output）。DSM 的 start 只寫入要求就返回，所以 `dsm-scripts/postinst`、`postupgrade`、`start` 看不到它的結果；root 的清理或遷移放 `root.start`，非特權的收尾放 `dsm-scripts/`。宣告 `root.start` 會改變 policy digest，需要管理員重新核准；沒有宣告的 App policy 不變。需要 SDK 0.10.3 以上。
+start、stop 步驟與 `uninstall.purge.root` 都以 root、無 session 執行，只在管理員核准有效時跑；這些程式不能宣告 run 或 job（session 要用時以另一個名稱設定，可指向同一份內容）。start 步驟在新版本第一次啟動、executor 開 socket 並回讀核准任務之後執行，預設最多 60 秒；若宣告 lifecycle budget，則從核准的 start 剩餘預算扣除收尾餘裕；執行期間 executor 只回應 `status`（`state: "starting"`），其他請求回可重試的 `EXECUTOR_STARTING`，DSM 視窗的核准會等它結束，狀態讀取則立即回 `executor_starting`、由 SDK 面板自行重試，失敗只寫進 executor log，不擋啟動；同一版本不重跑，程式要能重複執行。結果由 executor `status` 的 `start_step` 讀取（`pending`、`ok`、`failed`，含 exit 與 output）。DSM 的 start 只寫入要求就返回，所以 `dsm-scripts/postinst`、`postupgrade`、`start` 看不到它的結果；root 的清理或遷移放 `root.start`，非特權的收尾放 `dsm-scripts/`。宣告 `root.start` 會改變 policy digest，需要管理員重新核准；沒有宣告的 App policy 不變。需要 SDK 0.10.3 以上。
 
 schema 是 executor 的封閉子集（每個 object 都要 `additionalProperties: false`，key `[a-z0-9_]`，pattern 為 RE2）。這些設定需要支援它們的 SDK executor（`EXECUTOR_ROOT_PROGRAMS_UNSUPPORTED`）。preupgrade 呼叫 `executor/lifecycle stop --upgrade`；舊 SDK 的 helper 不認得此旗標時改用一般 stop。
 

package/skills/reference/lifecycle.md

@@ -108,3 +108,28 @@ A silent upgrade has no wizard values; use a default.
   change they made.
 - An upgrade runs the old package's preuninst and postuninst; check
   `SYNOPKG_PKG_STATUS` before deleting anything.
+
+## Work budgets
+
+Use existing `daemon.timeouts` for start/stop/status/uninstall (defaults
+30/30/5/60 seconds). Start/stop/uninstall accept 2–3600 seconds and status accepts
+1–3600. A `daemon` containing only `timeouts` declares budgets without an
+executable, including background and Compose Apps; Compose start still uses
+`compose.startup_timeout_seconds` (120, 2–900). Background user-manager recovery
+uses the start allowance and its generated package user unit uses the stop
+allowance with `KillMode=control-group`.
+
+`backend.timeout_seconds` owns request/operation work. Binary and Compose Apps
+without a CGI request setting can enlarge the shared operation allowance through
+`daemon.timeouts.status` above its 60-second default. Generated gateway and
+approved executor configurations inherit it; nested calls use remaining time and
+leave response reserve. Budget changes in the protected policy require renewed
+approval and do not change token/session/grant lifetimes.
+
+`uninstall.purge.timeout` accepts 2–3600 seconds and includes termination reserve.
+A timeout is logged and may leave `uninstall-hook.pending`; the uninstall may
+continue. The executor helper's JSON state distinguishes `accepted`,
+`cleanup-complete` and `cleanup-pending`. An exit of zero acknowledges the retained
+request and does not prove cleanup finished. Unconfirmed cleanup retains protected
+state for a later retry. DSM's outer install/uninstall deadline is not established
+by these settings.