@synopackageland/cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.20.0 (2026-10-21)
+
+- Align CLI/templates and the supported SDK minor line at 0.20; retain published UI 0.12.5.
+- Compare upgrade approval requirements with `build/inspect --baseline`.
+- Package native Compose shared-folder mounts with `select: install` and pass host health readiness to the daemon.
+- Pin the 0.20.0 executor/lifecycle digest inventory and refresh canonical approval fixtures. Rebuilt executor Apps require administrator reapproval after upgrade.
+
+## 0.19.1 (2026-10-20)
+
+- Record SDK 0.19.1 executor and lifecycle digests for the executor fix that accepts `deadline_ms` on delegated `webapi.call`; SDK 0.19.0 digests remain. Executor Apps rebuilt with SDK 0.19.1 require one administrator reapproval after upgrading.
+- Compare upgrade approval requirements with a baseline SPK: `build --baseline` and `inspect --baseline` report root program digests, policy differences, task template changes and executor-only handoff eligibility.
+- Retain templates 0.19.0 (SDK 0.19.0) and UI 0.12.5.
+
 ## 0.19.0 (2026-10-20)
 
 - Align the CLI SDK minor line and templates at 0.19.0; retain UI 0.12.5.

package/README.md

@@ -119,6 +119,19 @@ window's approval waits for it, while a status read answers `executor_starting`
 SDK's panels check again on their own. The program cannot declare `run` or `job`, and
 declaring it changes the policy digest, so an administrator approves the App again.
 
+Before releasing an executor App, compare it with the previous released SPK of
+that package and architecture. Include the resulting summary in release notes:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous.spk --json
+synopkgland inspect current.spk --baseline previous.spk
+```
+
+The summary covers root program digests, permission/parameter differences, task
+template changes and executor-only handover eligibility. Without a comparable
+baseline, approval retention is unknown. Eligibility still requires live protected
+runtime and exact DSM task readback. See [the approval guide](skills/reference/approval-upgrades.md).
+
 ## Commands
 
 | Command | Purpose |

package/dist/cli.js

@@ -33,6 +33,7 @@ import { buildNativeLayout, isNativeLayout, loadNativeLayout, LAYOUT_ARCHES, } f
 import { buildStandalone, runnerFor } from "./standalone/build.js";
 import { checkJobs, commitOutputs, forEachArch, } from "./standalone/arch-jobs.js";
 import { checkReproducible } from "./reproducible.js";
+import { spkApprovalDiff, formatApprovalDiff } from "./runtime/approval-diff.js";
 import { inspectAnySpk } from "./spk/inspect.js";
 function failure(code, message, hint = "Fix the configuration and retry; use --help to see command usage.") {
     return Object.assign(new Error(codedMessage(code, message)), { code, hint });
@@ -389,16 +390,18 @@ export async function runCli(argv) {
     });
     program
         .command("inspect <spk>")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK")
         .description("Inspect any SPK against the DSM 7 package format without installing; for a synopkgland-built SPK also check the build contract and root privilege requirements")
         .option("--json", "Print a single JSON object")
-        .action(async (input) => {
+        .action(async (input, options) => {
         const spk = resolve(input);
         if (existsSync(spk) && statSync(spk).isDirectory())
             throw failure("SPK_INSPECTION_FAILED", `${spk} is a directory; inspect checks .spk files.`, "Use synopkgland check to inspect project settings.");
         const report = await inspectAnySpk(spk);
         if (!report.dsm.ok || report.findings.length)
             throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "Fix the SPK by error code and repackage; see reference/errors for the codes; do not install an SPK that fails inspection."), { report: { spk, ...report } });
-        emit("inspect", { spk, ...report }, formatSpkReport(spk, report));
+        const approval = await spkApprovalDiff(spk, options.baseline && resolve(options.baseline), report);
+        emit("inspect", { spk, ...report, approval }, formatSpkReport(spk, report) + "\n" + formatApprovalDiff(approval));
     });
     const images = program.command("images").description("Container image tools");
     images
@@ -624,6 +627,7 @@ export async function runCli(argv) {
     skill.command("show <id>").action((id) => stdout(readSkill(id)));
     program
         .command("build")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK (one matching architecture)")
         .description("Build an SPK from synology-app.yaml or dsm-package.yaml")
         .option("--json", "Print a single JSON object")
         .option("-o, --output <path>", "Output SPK; use with a single --arch")
@@ -684,13 +688,15 @@ export async function runCli(argv) {
                         outDir: undefined,
                     }),
             });
+        const approval = await Promise.all(outputs.map(async (output) => ({ output, ...await spkApprovalDiff(output, options.baseline && resolve(options.baseline)) })));
         const lines = [
+            ...approval.map(item => item.output + "\n" + formatApprovalDiff(item)),
             ...outputs.map((output) => `Built ${output}`),
             ...(reproducible ? reproducibleLines(reproducible) : []),
         ];
         if (reproducible && !reproducible.identical)
             throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "Find the payload files that differ between builds (timestamps, random paths, unpinned dependencies) and retry after fixing them."), { report: { outputs, reproducible } });
-        emit("build", { outputs, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
+        emit("build", { outputs, approval, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
         console.log = (...args) => console.error(...args);

package/dist/deploy/native-install-values.d.ts

@@ -8,9 +8,9 @@ export type NativeInstallValuesResult = {
     message: string;
 };
 /**
- * Install wizard values for a native-go/binary deploy. Only an install-selected
- * delegate asks the wizard for anything; preinst refuses an empty selection on
- * the first install, so refuse it here before building or uploading.
+ * Install wizard values for native and Compose deployment. An install-selected
+ * delegate or install.sharedFolder asks the wizard for a selection. Reject
+ * missing first-install answers before building or uploading.
  */
 export declare function resolveNativeInstallValues(manifest: StandaloneManifest, provided: Record<string, string>, state: {
     installed: boolean;

package/dist/deploy/native-install-values.js

@@ -6,20 +6,34 @@ function validShareName(name) {
         !/^homes?$/i.test(name) && name.trim() === name && name.length <= 256);
 }
 /**
- * Install wizard values for a native-go/binary deploy. Only an install-selected
- * delegate asks the wizard for anything; preinst refuses an empty selection on
- * the first install, so refuse it here before building or uploading.
+ * Install wizard values for native and Compose deployment. An install-selected
+ * delegate or install.sharedFolder asks the wizard for a selection. Reject
+ * missing first-install answers before building or uploading.
  */
 export function resolveNativeInstallValues(manifest, provided, state) {
     const fail = (code, message) => ({ ok: false, code, message });
     const selected = manifest.capabilities.delegate?.scope === "install-selected";
+    const folder = manifest.sharedFolder?.mode === "select" ? manifest.sharedFolder : undefined;
+    const key = folder?.key;
+    const changeKey = key ? `CHANGE_${key}` : undefined;
     const names = Object.keys(provided);
-    if (!selected && names.length)
+    if (!selected && !folder && names.length)
         return fail("DEPLOY_PARAM_UNDECLARED", `${manifest.package} has no install wizard values; remove --param ${names[0]}.`);
-    const unknown = names.find((name) => name !== "delegate_share" && name !== "delegate_home");
+    const unknown = names.find((name) => !(selected && (name === "delegate_share" || name === "delegate_home")) && name !== key && name !== changeKey);
     if (unknown)
-        return fail("DEPLOY_PARAM_UNDECLARED", `--param ${unknown} is not an install wizard value. Use: ${USAGE}.`);
-    const { delegate_share: share, delegate_home: home } = provided;
+        return fail("DEPLOY_PARAM_UNDECLARED", `--param ${unknown} is not an install wizard value. Use: ${folder ? `--param ${folder.key}=<shared folder>` : USAGE}.`);
+    if (key && changeKey) {
+        const name = provided[key], change = provided[changeKey];
+        if (change !== undefined && change !== "true" && change !== "false")
+            return fail("DEPLOY_PARAM_TYPE_INVALID", `--param ${changeKey} must be true or false.`);
+        if (name !== undefined && (name === "" || /[/\\"\x00-\x1f\x7f]/.test(name) || name.includes("..") || /^[.@]/.test(name)))
+            return fail("DEPLOY_PARAM_TYPE_INVALID", `--param ${key} must be one DSM Shared Folder name, never a path.`);
+        if ((!state.installed || change === "true") && name === undefined)
+            return fail("DEPLOY_PARAM_REQUIRED", `Select the native Shared Folder with --param ${key}=<shared folder>.`);
+        if (state.installed && name !== undefined && change !== "true")
+            return fail("DEPLOY_PARAM_REQUIRED", `Changing the selected folder requires --param ${changeKey}=true and --param ${key}=<shared folder>.`);
+    }
+    const share = selected ? provided.delegate_share : undefined, home = selected ? provided.delegate_home : undefined;
     if (home !== undefined && home !== "true" && home !== "false")
         return fail("DEPLOY_PARAM_TYPE_INVALID", "--param delegate_home must be true or false.");
     if (share !== undefined && !validShareName(share))

package/dist/error-registry.js

@@ -11,6 +11,7 @@ export const ERROR_REGISTRY = {
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },
     CTL_COMMAND_UNREGISTERED: { "code": "CTL_COMMAND_UNREGISTERED", "description": "A command references an unregistered backend method.", "suggestion": "Correct ctl.commands bindings or register the backend method." },
     CTL_DESCRIPTOR_INVALID: { "code": "CTL_DESCRIPTOR_INVALID", "description": "The generated API description violates the public contract.", "suggestion": "Correct ctl.commands and rebuild the private synopkgland-api.json." },
+    APPROVAL_BASELINE_INVALID: { code: "APPROVAL_BASELINE_INVALID", description: "The --baseline SPK failed inspection, so approval retention cannot be compared.", suggestion: "Pass the previous released SPK of the same package and architecture, unmodified; inspect it to see each finding." },
     CTL_DECLARATION_INVALID: { "code": "CTL_DECLARATION_INVALID", "description": "The ctl declaration is invalid.", "suggestion": "Check ctl.enabled, aliases and explicit commands in dsm-package.yaml." },
     ...{
         LAUNCHER_PORTAL_MISMATCH: {

package/dist/runtime/approval-diff.d.ts

@@ -0,0 +1,37 @@
+import type { ExecutorPolicy } from './executor-policy.js';
+import { type SpkReport } from '../spk/inspect.js';
+export interface ApprovalInventory {
+    package: string;
+    arch: string;
+    executorDigest: string;
+    policyDigest: string;
+    anchored: boolean;
+    policy: ExecutorPolicy;
+    tasks: Array<{
+        kind: string;
+        name: string;
+        script: string;
+    }>;
+}
+export interface ApprovalDifference {
+    retention: 'unknown' | 'eligible' | 'required';
+    permissions: 'unknown' | 'unchanged' | 'expanded' | 'review-required';
+    executor_only: boolean;
+    task_template_changed: boolean | null;
+    old_policy_digest?: string;
+    new_policy_digest?: string;
+    root_programs: Array<{
+        name: string;
+        old: string | null;
+        new: string | null;
+    }>;
+    policy_changes: Array<{
+        path: string;
+        old: unknown;
+        new: unknown;
+    }>;
+    reason: string;
+}
+export declare function approvalDiff(old: ApprovalInventory | undefined, next: ApprovalInventory | undefined): ApprovalDifference;
+export declare function spkApprovalDiff(current: string, baseline?: string, report?: SpkReport): Promise<ApprovalDifference>;
+export declare function formatApprovalDiff(d: ApprovalDifference): string;

package/dist/runtime/approval-diff.js

@@ -0,0 +1,56 @@
+import { inspectAnySpk } from '../spk/inspect.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value) ?? 'null';
+}
+function authority(policy) {
+    const p = structuredClone(policy);
+    p.root = Object.fromEntries(Object.entries(policy.root).map(([name, entry]) => [name, typeof entry === 'string' ? {} : Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'digest'))]));
+    return p;
+}
+function changes(a, b, path = '', out = []) {
+    if (canonical(a) === canonical(b))
+        return out;
+    if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort())
+            changes(a[key], b[key], path + '/' + key.replaceAll('~', '~0').replaceAll('/', '~1'), out);
+    }
+    else
+        out.push({ path, old: a ?? null, new: b ?? null });
+    return out;
+}
+const rootDigests = (p) => Object.fromEntries(Object.entries(p.root).map(([name, e]) => [name, typeof e === 'string' ? e : e.digest]));
+export function approvalDiff(old, next) {
+    const unknown = { retention: 'unknown', permissions: 'unknown', executor_only: false, task_template_changed: null, root_programs: [], policy_changes: [], reason: 'Cannot determine whether approval can be retained: a valid, matching baseline SPK and executor inventory are required.' };
+    if (!old || !next || old.package !== next.package || old.arch !== next.arch)
+        return unknown;
+    const a = rootDigests(old.policy), b = rootDigests(next.policy);
+    const root_programs = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort().filter(name => a[name] !== b[name]).map(name => ({ name, old: a[name] ?? null, new: b[name] ?? null }));
+    const policy_changes = changes(authority(old.policy), authority(next.policy));
+    const expanded = next.policy.operations.some(op => !old.policy.operations.includes(op)) || Object.keys(next.policy.root).some(name => !(name in old.policy.root));
+    const templates = (i) => i.tasks.map(t => ({ kind: t.kind, name: t.name, script: t.script.replaceAll(i.policyDigest, '@POLICY_DIGEST@') })).sort((a, b) => a.kind < b.kind ? -1 : 1);
+    const task_template_changed = canonical(templates(old)) !== canonical(templates(next));
+    const eligible = old.policyDigest === next.policyDigest && !task_template_changed && (old.executorDigest === next.executorDigest || next.anchored);
+    return { retention: eligible ? 'eligible' : 'required', permissions: expanded ? 'expanded' : policy_changes.length ? 'review-required' : 'unchanged', executor_only: eligible && old.executorDigest !== next.executorDigest, task_template_changed, old_policy_digest: old.policyDigest, new_policy_digest: next.policyDigest, root_programs, policy_changes, reason: eligible ? 'Approval can be retained if the installed protected runtime and exact DSM task readback still match this baseline.' : 'Administrator reapproval is required for the changed payload, policy, executor anchor or task definitions.' };
+}
+function inventory(r) {
+    if (!r.dsm.ok || r.findings.length || !r.executor || !r.package || !r.arch)
+        return;
+    return { package: r.package, arch: r.arch, ...r.executor, anchored: true }; // inspect verifies the INFO anchor and every root payload digest.
+}
+export async function spkApprovalDiff(current, baseline, report) {
+    if (!baseline)
+        return approvalDiff(undefined, undefined);
+    const next = inventory(report ?? await inspectAnySpk(current));
+    const old = await inspectAnySpk(baseline);
+    if (!old.dsm.ok || old.findings.length)
+        throw new Error('[APPROVAL_BASELINE_INVALID] Baseline SPK failed inspection: ' + [...old.findings, ...old.dsm.errors.map(e => e.message)].join('; '));
+    return approvalDiff(inventory(old), next);
+}
+export function formatApprovalDiff(d) {
+    const short = (s) => s?.slice(0, 12) ?? '—';
+    return ['Approval: ' + d.reason, 'Permissions: ' + d.permissions, ...d.root_programs.map(p => `Root program ${p.name}: ${short(p.old)} → ${short(p.new)}`), ...d.policy_changes.map(c => `Policy ${c.path}: ${JSON.stringify(c.old)} → ${JSON.stringify(c.new)}`), `Task template: ${d.task_template_changed === null ? 'unknown' : d.task_template_changed ? 'changed' : 'unchanged'}`, `Executor-only handover: ${d.executor_only ? 'eligible under the INFO anchor' : 'not established'}`].join('\n');
+}

package/dist/runtime/executor-digests.json

@@ -1,13 +1 @@
-{
-    "0.19.0": {
-        "x86_64": "3b23252a4d2ad188e8920aee3c022d054a85f31797dfb9f34a576449f8b08f41",
-        "aarch64": "024a8a01977324645b475330371afb8b8c8387eac6a11ec3d9d30a4a0e445174",
-        "armv7": "fae3266f65863815f1417332a3c73d12507941029077e0ddc118da8461e8cff3",
-        "lifecycle": {
-            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
-            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
-            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
-        },
-        "goToolchain": "go1.26.9"
-    }
-}
+{ "0.20.0": { "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa", "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191", "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc", "lifecycle": { "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972", "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb", "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681" }, "goToolchain": "go1.26.9" } }

package/dist/standalone/compose-errors.js

@@ -212,13 +212,13 @@ export const COMPOSE_ERRORS = {
     },
     COMPOSE_SHARE_INVALID: {
         code: "COMPOSE_SHARE_INVALID",
-        description: "Shares.the declared value needs admin selection, ro/rw and fixed mounts.",
-        suggestion: "Keep the project disabled until an official protected mount/project adapter is verified; never use a destination grant or host root workaround.",
+        description: "Shared Folder selection, permission or fixed mount declaration is invalid.",
+        suggestion: "For select: install, match install.sharedFolder mode: select, key and permission; choose an existing unambiguous folder. Dynamic admin-after-install remains blocked. Never use a destination grant or host root workaround.",
     },
     COMPOSE_SHARE_NEEDS_APPROVAL: {
         code: "COMPOSE_SHARE_NEEDS_APPROVAL",
         description: "Declare capabilities.composeMounts: true; user destination grants cannot authorize package mounts.",
-        suggestion: "Keep the project disabled until an official protected mount/project adapter is verified; never use a destination grant or host root workaround.",
+        suggestion: "Declare the package-wide composeMounts opt-in. Native install selection requires DSM package-user permission; dynamic admin-after-install remains blocked.",
     },
     COMPOSE_SOURCE_UNSAFE: {
         code: "COMPOSE_SOURCE_UNSAFE",

package/dist/standalone/compose.d.ts

@@ -1,6 +1,7 @@
 import { type ComposeAppData } from "../runtime/compose-data.js";
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import { type Daemon } from "./daemon.js";
+import type { SharedFolder } from "./shared-folder.js";
 import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface ComposePlan {
     app_data?: ComposeAppData;
@@ -77,6 +78,7 @@ export declare function readComposeApp(value: unknown, root: string, arches: Nat
     sdk?: string;
     mode?: string;
     composeMounts?: boolean;
+    sharedFolder?: SharedFolder;
     resolveImages?: boolean;
     architecture?: NativeArchFamily;
     imageProofs?: unknown;
@@ -85,12 +87,12 @@ export declare function composeDaemon(m: Pick<StandaloneManifest, "compose" | "l
 export declare function composeNetwork(m: Pick<StandaloneManifest, "compose" | "identityGateway" | "spkVersion">): {
     public_ports: number[];
     readiness?: {
-        version: string;
-        plan_sha256: string;
         health: {
             path: string;
             status: number;
         } | undefined;
+        version?: string | undefined;
+        plan_sha256?: string | undefined;
     } | undefined;
     ingress?: {
         candidate: number;
@@ -101,7 +103,7 @@ export declare function composeNetwork(m: Pick<StandaloneManifest, "compose" | "
 export declare function composeSource(c: ComposeApp): string;
 /** Retain upstream bytes, the true override and a lock without secret values. */
 export declare function writeComposePayload(c: ComposeApp, root: string, target: string, gateway?: unknown): void;
-/** Only package identity values are materialized, in the incoming tree. */
+/** Materialize fixed package identity and native wizard share names in the incoming tree. */
 export declare function renderComposeInstall(pkg: string): string;
 /** The same SDK entry point supplies the package-account install materializer. */
 export declare function buildComposeControl(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: import("./build.js").CommandRunner): Promise<string | undefined>;
@@ -118,3 +120,4 @@ export declare function dsmComposeProblem(c: ComposeApp): {
     message: string;
 } | undefined;
 export declare const COMPOSE_READINESS_LIMITATION = "Availability only: App health + fixed endpoint TCP + package lifecycle acquire generation matching the installed version. This does not attest the actual Docker image, project or generation. Another process already executing locally on the NAS may impersonate the fixed endpoint. Accepted for this local-code-execution threat model; replace with full official readback when available.";
+export declare const COMPOSE_HOST_READINESS_LIMITATION = "Host availability only: package UID and loopback listener bindings, plus declared App HTTP health when configured. This does not attest the actual Docker image, project or generation.";

package/dist/standalone/compose.js

@@ -93,6 +93,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
                 package: context.package ?? "ComposeApp",
                 identity_mode: context.mode ?? "none",
                 compose_mounts: context.composeMounts === true,
+                ...(context.sharedFolder?.mode === "select" ? { install_shared_folder: context.sharedFolder } : {}),
                 resolve_images: context.resolveImages === true,
                 registry_mirrors: context.resolveImages &&
                     process.env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS
@@ -171,11 +172,10 @@ export function composeNetwork(m) {
         ...(c.plan.ingress
             ? { ingress: { candidate: c.plan.ingress.candidate } }
             : {}),
-        ...(!host && c.web && !c.plan.mounts_blocked
+        ...(c.web && (!host || c.web.health) && !c.plan.mounts_blocked
             ? {
                 readiness: {
-                    version: m.spkVersion,
-                    plan_sha256: c.plan.sha256,
+                    ...(!host ? { version: m.spkVersion, plan_sha256: c.plan.sha256 } : {}),
                     health: c.web.health,
                 },
             }
@@ -207,7 +207,7 @@ export function writeComposePayload(c, root, target, gateway) {
     }))
         writeFileSync(join(target, name), content, { mode: 0o600 });
 }
-/** Only package identity values are materialized, in the incoming tree. */
+/** Materialize fixed package identity and native wizard share names in the incoming tree. */
 export function renderComposeInstall(pkg) {
     return `#!/bin/sh
 set -eu
@@ -268,6 +268,7 @@ export function lockComposeImages(m, arch, resolveImages, imageProofs) {
         sdk: m.compose.sdk,
         mode: m.identityGateway?.mode ?? "none",
         composeMounts: m.capabilities.composeMounts,
+        sharedFolder: m.sharedFolder,
         resolveImages,
         architecture: arch,
         imageProofs,
@@ -346,3 +347,4 @@ export function dsmComposeProblem(c) {
         };
 }
 export const COMPOSE_READINESS_LIMITATION = "Availability only: App health + fixed endpoint TCP + package lifecycle acquire generation matching the installed version. This does not attest the actual Docker image, project or generation. Another process already executing locally on the NAS may impersonate the fixed endpoint. Accepted for this local-code-execution threat model; replace with full official readback when available.";
+export const COMPOSE_HOST_READINESS_LIMITATION = "Host availability only: package UID and loopback listener bindings, plus declared App HTTP health when configured. This does not attest the actual Docker image, project or generation.";

package/dist/standalone/inspect-spk.js

@@ -6,7 +6,7 @@ import { inspectApiDescription } from "./api-description-inspect.js";
 import { dsmLauncherType } from "../contract/app-launch.js";
 import { isWebLaunchMode, resolvedWebLaunch, trustedAppEntryPath, usesAuthGateway, } from "../contract/web-launch.js";
 import { loadContract } from "../contract/load.js";
-import { readComposeApp, composeSource, dsmComposeProblem, COMPOSE_READINESS_LIMITATION, } from "./compose.js";
+import { readComposeApp, composeSource, dsmComposeProblem, COMPOSE_READINESS_LIMITATION, COMPOSE_HOST_READINESS_LIMITATION, } from "./compose.js";
 import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
 import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
@@ -575,6 +575,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             requiresAdminApproval: true,
         })),
     };
+    const appScripts = unwrapAppScripts(join(dir, "scripts"), findings);
     const root = join(dir, "unified-compose-inspection");
     mkdirSync(root);
     await tar.x({ file: join(dir, "package.tgz"), cwd: root });
@@ -596,6 +597,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             sdk: saved.sdk,
             mode: cfg?.mode ?? "none",
             composeMounts: metadata.capabilities?.includes("composeMounts"),
+            sharedFolder: recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))),
             architecture: arch,
             imageProofs: JSON.parse(readFileSync(join(root, "compose/images.json"), "utf8")),
         });
@@ -641,6 +643,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
                     : {}),
             },
             compose: c,
+            sharedFolder: recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))),
             ...(g ? { identityGateway: g } : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
         };
@@ -650,6 +653,11 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             throw new Error("gateway configuration differs from the declared package contract");
         if (readOptional(join(dir, "conf/privilege")) !== renderNativePrivilege())
             throw new Error("Compose hooks must run as the package account");
+        if (manifest.sharedFolder) {
+            for (const [name, text] of Object.entries(expectedWizardFiles(info.package, manifest.sharedFolder)))
+                if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
+                    throw new Error(`unexpected WIZARD_UIFILES/${name}; native share selection must match the declaration`);
+        }
         const resource = renderStandaloneResource(manifest);
         if (readOptional(join(dir, "conf/resource")) !== resource)
             throw new Error("unexpected worker resource; unapproved Shares must never auto-acquire");
@@ -671,7 +679,6 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
                 throw new Error(`unexpected WIZARD_UIFILES/${name}; retained-volume guidance must match the plan`);
         }
-        const appScripts = unwrapAppScripts(join(dir, "scripts"), findings);
         manifest.appScripts = undefined;
         for (const hook of [
             "preinst",
@@ -737,9 +744,10 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
                         ? "none"
                         : c.plan.services.find((s) => s.service === c.web?.service)
                             ?.network === "host"
-                            ? "host-uid-listener"
+                            ? c.web.health ? "host-uid-listener-health" : "host-uid-listener"
                             : "health-fixed-ip-lifecycle",
-                limitation: COMPOSE_READINESS_LIMITATION,
+                limitation: c.plan.services.find((s) => s.service === c.web?.service)?.network === "host"
+                    ? COMPOSE_HOST_READINESS_LIMITATION : COMPOSE_READINESS_LIMITATION,
             },
         };
     }

package/dist/standalone/lifecycle.js

@@ -33,7 +33,8 @@ function renderStandaloneScriptInternal(name, manifest) {
         const control = `"/var/packages/${manifest.package}/target/daemon/control"`;
         const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${manifest.package}/var}"`;
         const preflight = name === "start-stop-status"
-            ? `case "$1" in prestart|start|restart)\n  "\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/compose/control" preflight || exit $? ;;\nesac\n`
+            ? `case "$1" in prestart|start|restart)\n  "\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/compose/control" preflight || exit $? ;;\nesac\n` +
+                (!manifest.identityGateway ? `case "$1" in prestart|prestop) exit 0 ;; esac\n` : "")
             : "";
         const remember = name === "postinst" &&
             manifest.compose.plan.ingress &&

package/dist/standalone/manifest.js

@@ -240,12 +240,16 @@ function readManifest(raw, c) {
         c.fail("CTL_UNSUPPORTED_BACKEND", "Compose does not support automatic ctl descriptions; disable ctl.");
     if (isRecord(raw.compose) && isRecord(raw.compose.web) && !isRecord(raw.compose.web.health))
         c.fail("COMPOSE_HEALTH_REQUIRED", "Select compose.web.health.path and expected 2xx status for the actual App. Readiness does not follow redirects; check is static and does not probe HTTP.");
+    const sharedFolder = raw.install === undefined
+        ? undefined
+        : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
     const compose = arches &&
         readComposeApp(raw.compose, c.root, arches, (e) => c.fail(e.code, e.message), {
             package: packageId,
             sdk: typeof gatewayRaw.sdk === "string" ? gatewayRaw.sdk : undefined,
             mode: typeof gatewayRaw.mode === "string" ? gatewayRaw.mode : "none",
             composeMounts: capabilities.composeMounts,
+            sharedFolder,
         });
     if (raw.compose !== undefined &&
         ((raw.daemon !== undefined && !timeoutOnly) ||
@@ -306,9 +310,6 @@ function readManifest(raw, c) {
         if (permissions)
             checkBridgeMethods(backend, permissions, c);
     }
-    const sharedFolder = raw.install === undefined
-        ? undefined
-        : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
     const entry = raw.entry === undefined
         ? undefined
         : raw.compose !== undefined &&

package/dist/standalone/root-window.js

@@ -359,9 +359,14 @@ export const ROOT_RUNTIME = `function createRootAccess(options) {
   // here, and that first status serves the health check. Approval and
   // control read back on their own.
   function checked(status) { return pinned(status) && !!status.tasks && status.tasks.state === "ready"; }
+  function approvalExplanation(verified, status) {
+    var diff = status && status.approval;
+    if (verified.state === "needs-admin-approval" && diff && options.pins && diff.package === options.pins.package && diff.new_policy_digest === options.pins.policyDigest && diff.new_executor_digest === options.pins.executorDigest && (diff.old_policy_digest !== diff.new_policy_digest || diff.task_template_changed)) verified.approval = diff;
+    return verified;
+  }
   function adminStatus() {
     var asked = options.call("executor.status", {});
-    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }); }
+    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }).then(function (verified) { return asked.then(function (status) { return approvalExplanation(verified, status); }, function () { return verified; }); }); }
     return asked.then(function (status) {
       return checked(status) ? {state: "ready", tasks: {boot: {state: "ready"}, control: {state: "ready"}}, executor: status} : verify();
     }, verify);

package/package.json

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

package/skills/SKILL.md

@@ -5,6 +5,8 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
+Before releasing an executor App, read [reference/approval-upgrades.md](reference/approval-upgrades.md). Run build/inspect with the previous released SPK as `--baseline` and include the approval difference in release notes. Without a comparable baseline, retention is unknown.
+
 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.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.

package/skills/reference/approval-upgrades.md

@@ -0,0 +1,36 @@
+# Approval changes before release
+
+Run the current CLI against the previous released SPK for the same package and
+architecture before releasing an executor App:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous-x86_64.spk --json
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk --json
+```
+
+`inspect` returns `data.approval`; `build` returns one entry per output in
+`data.approval`. Put the human summary in release notes. Optionally copy that
+same summary into the manifest's `metadata.changelog`, which the existing build writes to INFO for Package Center.
+Do not assume DSM automatically opens an App after upgrading it.
+
+The summary names root programs and their old/new SHA-256 prefixes, policy
+permission/parameter paths, and task template changes. Task template comparison
+removes only the policy pin; a policy pin change still requires approval.
+`unchanged` means the policy excluding root digests is identical. Added root
+programs or operations are `expanded`; other permission/parameter changes are
+`review-required`, because arbitrary schema and scope changes cannot generally
+be proven to narrow permissions. Program bytes can change behavior even when
+the declared policy is unchanged.
+
+`eligible` is conditional: the live protected runtime must still match the
+baseline and DSM must read back the exact approved tasks. An executor-only
+handover additionally needs the new executor's valid INFO anchor. This offline
+summary does not grant approval. With no baseline, an incompatible package or
+architecture, or no executor inventory, retention is `unknown`; never promise
+that approval will be retained. Invalid baselines fail inspection.
+
+The SDK approval screen reads root-produced diagnostics through executor.status,
+then uses the existing PasswordConfirm and exact task readback. Older protected
+runtimes without diagnostic support show an explicit unknown explanation. No App
+option supplies an approved baseline or permission claim.

package/skills/reference/compose.md

@@ -98,7 +98,7 @@ a build operator trust decision. `check`/`inspect` remain offline.
 | Private bind data | DSM build rejects COMPOSE_PRIVATE_BIND_TIMING_UNSUPPORTED: clean-install preinst precedes pkgvar creation, while worker acquire precedes postinst; no root initialization or automatic volume conversion |
 | Image VOLUME | Build inventories verified image config and assigns a stable named volume |
 | Existing external volume | Rejected without trusted admin ownership/driver readback |
-| Existing Shared Folder | Explicit opt-in intent only; blocked settings page until official protected ACL/project control exists |
+| Existing Shared Folder | Native install selection plus DSM package-user ACL; dynamic admin-after-install authority stays blocked |
 | Bridge | Default no-publish dedicated internal bridge with a package-derived fixed IP; availability requires App health, TCP and the current lifecycle acquire record; no Docker identity attestation |
 | Host | Explicit verified OIDC web consumer with address_env forced to 127.0.0.1; no container-root; internet access is visible |
 | Egress | isolated internal networks, or explicit internet outbound bridge; fine allowlist declarations fail |
@@ -122,7 +122,48 @@ modification and deletion. DSM identity/account bridge and file authority are
 separate features. Per-DSM-user filesystem access requires a File Station session
 or Broker Adapter; it is outside this change and cannot be obtained through a mount.
 
-Declare `capabilities: {composeMounts: true}` and, for example:
+For one existing Shared Folder, reuse the native install/upgrade wizard:
+
+```yaml
+capabilities: {composeMounts: true}
+install:
+  sharedFolder: {mode: select, key: media, permission: ro}
+compose:
+  shares:
+    media:
+      select: install
+      # Omitted permission defaults to ro. For rw, set rw in both declarations.
+      mounts: [{service: web, target: /media}]
+```
+
+The share key and permission must match `install.sharedFolder` exactly. This
+route supports `mode: select`; `create` resource ordering is not supported.
+The package-account preinst resolves the chosen name on `/volumeN` and writes
+only the fixed source placeholder into the worker's private `.env`. Missing,
+ambiguous or symlinked sources fail installation. Host paths are never wizard
+answers. Every mounted service uses the fixed package UID:GID, drops all Linux
+capabilities and has no-new-privileges. Container-root cannot mount Shares.
+
+**Selecting an existing share does not grant permission.** An administrator must
+grant the package account access in **Control Panel > Shared Folder > Edit >
+Permissions > System internal user**. Until then, container file operations fail
+under the kernel's ACL checks. No root helper, ACL writer or Docker socket is
+given to the App. Grant directly to the package account; supplementary DSM groups
+are not added to the container. See the SDK Shared Folder permission guide.
+
+The upgrade wizard keeps the saved name unless its change checkbox is selected.
+CLI deployment uses `--param media=Media` on first install, and
+`--param CHANGE_media=true --param media=OtherMedia` to change it on upgrade.
+Stop/disable and uninstall use DSM's official project worker; source data and
+administrator-managed ACL entries are retained. A moved share needs a new
+upgrade to resolve its volume path; start does not rematerialize the bind.
+
+ACL changes affect subsequent filesystem operations. Already-open file
+descriptors and data already read are not recalled. To stop existing streams,
+stop the package before removing its access. This native route does not promise
+automatic container termination or recreation on ACL changes.
+
+For dynamic selection after install, declare the separate, blocked authority:
 
 ```yaml
 compose:
@@ -140,13 +181,25 @@ upstream docker-project is acquired. The independent authority purpose is
 `compose-mount`; a user destination grant from Download Hub/delegate never
 permits a package-wide mount.
 
-The current implementation does **not** issue a mount grant, invoke ACL tools,
+The dynamic implementation does **not** issue a mount grant, invoke ACL tools,
 install a protected executor for Compose, or activate/revoke an upstream project.
 Confirmation returns `COMPOSE_PROJECT_CONTROL_UNAVAILABLE`. It must remain
 unsupported until an official ACL plus fixed project-control adapter can use
 protected policy/digest/generation authority, stop/recreate/read back and revoke
 without reviving stale grants. No app runs as host root to bypass this boundary.
 
+| Acceptance blocker | Native install selection |
+| --- | --- |
+| `DSM_DOCKER_PROJECT_MODEL` | Uses the existing official docker-project worker; device acceptance still applies. |
+| `DSM_STORAGE_OWNERSHIP_TIMING` | Existing shares need no package-created directory or chown; private package binds remain unsupported. |
+| `DSM_EGRESS_BOUNDARY` | Unchanged independent network acceptance condition. |
+| `COMPOSE_PROJECT_CONTROL_UNAVAILABLE` | Bypassed through native install/upgrade/stop/uninstall, without a dynamic controller. |
+| `DSM_MOUNT_ACL_REVOKE` | Native kernel ACL semantics above; immediate stream cancellation remains outside this route. |
+
+The first three general device acceptance labels remain in the plan. Dynamic
+`admin-after-install` and `install-draft` keep all five blockers and
+`mounts_blocked: true`; mixing dynamic authority with native selection is refused.
+
 ## Gateway transport
 
 `none` keeps native app login; `header`, `token` and embedded `oidc` use supported

package/skills/reference/deploy.md

@@ -5,7 +5,7 @@
 3. Review `synopkgland deploy --dry-run --arch x86_64`, which does not connect to a NAS.
 4. Only when installation is authorized, run `synopkgland deploy --host <profile>`.
 
-Deployment uploads directly to DSM. It does not publish artifacts. Compose uses schema-2 differences and fixed package identity. Existing Shared Folder intent requires admin confirmation after install; official protected ACL/project control is currently blocked. No install answer or user destination grant activates a package mount. See compose.md and its device acceptance blockers.
+Deployment uploads directly to DSM. It does not publish artifacts. Compose uses schema-2 differences and fixed package identity. For `compose.shares` with `select: install`, use matching `install.sharedFolder: {mode: select, key: media, permission: ro}` and pass `--param media=Media`. Upgrade keeps the selection unless `--param CHANGE_media=true --param media=OtherMedia` is provided. An administrator grants the fixed package account access through DSM; selection is not a grant. Dynamic admin-after-install protected ACL/project control remains blocked. A user destination grant never activates a package mount. See compose.md and its device acceptance blockers.
 
 For native-go root-ops, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Uninstall removes the executor tasks, the App's Application Privileges rules and a stale portal alias itself. Never delete installed packages or data as part of a code cleanup.