@synopackageland/cli 0.41.9 → 0.41.10

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.41.10 (2026-10-30)
+
+- Give DSM reads/login three minutes and SPK upload, install/upgrade and package
+  start/stop requests ten minutes by default, configurable through `DSM_*`
+  timeout variables.
+- After an install/upgrade response timeout, keep polling the requested version
+  and running state within a shared 30-minute install budget, with progress on
+  stderr. Preserve DSM failures and distinguish an exhausted budget from a
+  failed installation; never replay the install request.
+- Apply the same tolerant polling and progress to stop/uninstall, with a shared
+  configurable 30-minute budget and no write replay after response timeouts.
+- Load the optional AI provider only when `magpieAgent()` is called, so DSM
+  smoke suites import without `@ai-sdk/openai` or `ai` installed.
+- Share Compose registry-mirror configuration with `images pin`; verify returned
+  manifest bytes against the registry digest before writing the pin.
+
 ## 0.41.9 (2026-10-30)
 
 - Accept self-signed DSM and redirected gateway certificates by default in the

package/README.md

@@ -446,6 +446,15 @@ installation; official protected ACL/project control and bridge readback remain
 blocked. No SSO Server or wrapper container is added. Linux tests do not prove
 DSM readiness; inspect lists explicit acceptance blockers.
 
+`images pin` and the Compose planner share the build-host mirror configuration:
+`SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS='{"docker.io":"https://mirror.example.com"}'`.
+Each mirror must be an HTTPS origin. Image names retain their original registry;
+manifest bytes are hashed and checked against the registry's digest before pinning.
+
+`appOpenSmoke` and `dsmTarget` need only the optional `e2e` and `@e2e-dev/web`
+peers. The optional `@ai-sdk/openai` provider is loaded when `magpieAgent()` is
+called; install it and `ai` only for AI agent runs.
+
 ## Control installed Apps
 
 Use `synopkgland host add nas --url https://nas.example:5001 --username alice`
@@ -468,6 +477,31 @@ certificate checks. Strict failures use `HOST_TLS_UNTRUSTED` or `HOST_CERT_CHANG
 are sent only over a connection whose certificate was inspected. Public package
 feeds and SPK downloads retain normal HTTPS verification.
 
+DSM API requests tolerate slow NAS storage and startup. These environment
+variables also work in `.env`; each accepts integer seconds from 1 to 86400:
+
+| Variable | Default | Budget |
+| --- | ---: | --- |
+| `DSM_REQUEST_TIMEOUT_SECONDS` | 180 | One DSM read, login or other API request |
+| `DSM_OPERATION_TIMEOUT_SECONDS` | 600 | One SPK upload, install/upgrade compound, or package start/stop request |
+| `DSM_INSTALL_TIMEOUT_SECONDS` | 1800 | Per-package state check, upload, install/upgrade and startup together, in `install` and `deploy` |
+| `DSM_UNINSTALL_TIMEOUT_SECONDS` | 1800 | State check, stop and uninstall together |
+| `DSM_POLL_INTERVAL_SECONDS` | 5 | Package-state polling and progress interval |
+
+For example, set `DSM_INSTALL_TIMEOUT_SECONDS=3600` for an hour per package.
+An install/upgrade response timeout does not cancel DSM's work: the CLI keeps
+checking for the requested version **and running state**, without replaying the
+write. Progress continues on stderr, including with `--json`. A DSM failure
+reports `DSM_INSTALL_FAILED` and its reported details; an exhausted overall
+budget reports `DSM_INSTALL_TIMEOUT` and warns that DSM may still be working.
+Uninstall also keeps checking after stop/uninstall response or status timeouts,
+without replaying either write. Its exhausted budget reports `DSM_UNINSTALL_TIMEOUT`.
+Check Package Center before retrying. A timed-out same-version reinstall also
+needs an observed state transition before the old running instance can count
+as completion. Upload timeouts are reported separately because no install
+request has been sent yet. Explicit `ctl --timeout` budgets still take priority
+for `ctl` calls; App command/job/transfer deadlines retain their existing defaults.
+
 `ctl` preserves these process exit codes, including with `--json`:
 
 | Exit code | Meaning and examples |

package/dist/compose/registry-mirrors.d.ts

@@ -0,0 +1,3 @@
+/** Build-host registry policy shared by image pinning and SDK Compose planning. */
+export declare function composeRegistryMirrors(env?: NodeJS.ProcessEnv): Record<string, string> | undefined;
+export declare function registryBaseUrl(registry: string, mirrors?: Record<string, string> | undefined): string;

package/dist/compose/registry-mirrors.js

@@ -0,0 +1,38 @@
+/** Build-host registry policy shared by image pinning and SDK Compose planning. */
+export function composeRegistryMirrors(env = process.env) {
+    const raw = env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS;
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS must be a JSON object of registry HTTPS origins');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS must be a JSON object of registry HTTPS origins');
+    const mirrors = {};
+    for (const [registry, origin] of Object.entries(value)) {
+        let url;
+        try {
+            url = new URL(typeof origin === 'string' ? origin : '');
+        }
+        catch {
+            throw new Error('Registry mirror must be an HTTPS origin');
+        }
+        if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+            throw new Error('Registry mirror must be an HTTPS origin');
+        mirrors[registry] = url.origin;
+    }
+    return mirrors;
+}
+export function registryBaseUrl(registry, mirrors = composeRegistryMirrors()) {
+    const domain = registry === 'index.docker.io' ? 'docker.io' : registry;
+    if (mirrors && Object.hasOwn(mirrors, domain))
+        return mirrors[domain];
+    if (domain === 'docker.io')
+        return 'https://registry-1.docker.io';
+    const host = registry.startsWith('[') ? registry.slice(0, registry.indexOf(']') + 1) : registry.split(':')[0];
+    return `${['localhost', '127.0.0.1', '::1', '[::1]'].includes(host) ? 'http' : 'https'}://${registry}`;
+}

package/dist/e2e/dsm.js

@@ -19,7 +19,7 @@ import { connect, createServer } from "node:net";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createOpenAI } from "@ai-sdk/openai";
+import { createRequire } from "node:module";
 import { readSmokeEntry } from "./app-open.js";
 export { deriveSmokeEntry } from "./app-open.js";
 import { surfaceOf, test, web } from "@e2e-dev/web";
@@ -222,9 +222,21 @@ export function llmSettings(env = process.env) {
 }
 /** The `agents.default` entry of e2e.config.ts: model plus the effort sent with every request. */
 export function magpieAgent(env = process.env) {
+    // Keep the synchronous config API; load the optional ESM provider only when
+    // an agent is requested (Node 22.12+ supports require(esm)). Smoke tests do
+    // not need the AI SDK or any model provider installed.
+    let provider;
+    try {
+        provider = createRequire(import.meta.url)('@ai-sdk/openai');
+    }
+    catch (error) {
+        if (!['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes(error.code ?? ''))
+            throw error;
+        throw new Error('magpieAgent requires optional @ai-sdk/openai and ai; install them to run AI agents.', { cause: error });
+    }
     const settings = llmSettings(env);
     return {
-        model: createOpenAI({ baseURL: settings.baseURL, apiKey: settings.apiKey }).chat(settings.model),
+        model: provider.createOpenAI({ baseURL: settings.baseURL, apiKey: settings.apiKey }).chat(settings.model),
         providerOptions: { openai: { reasoningEffort: settings.reasoningEffort } },
     };
 }

package/dist/error-registry.js

@@ -5,6 +5,11 @@ export const ERROR_REGISTRY = {
     HOST_TLS_UNTRUSTED: { "code": "HOST_TLS_UNTRUSTED", "description": "Strict TLS: the NAS certificate failed CA, hostname or validity verification", "suggestion": "Check the CA file, NAS hostname and certificate validity, or omit strict TLS" },
     HOST_DNS_FAILED: { "code": "HOST_DNS_FAILED", "description": "The NAS hostname could not be resolved", "suggestion": "Check the registered hostname and DNS" },
     HOST_CONNECTION_REFUSED: { "code": "HOST_CONNECTION_REFUSED", "description": "The NAS refused the connection", "suggestion": "Check the DSM port and NAS availability" },
+    DSM_UNINSTALL_TIMEOUT: { code: 'DSM_UNINSTALL_TIMEOUT', description: 'The overall stop/uninstall budget was exhausted; DSM may still be working', suggestion: 'Check Package Center before retrying or increase DSM_UNINSTALL_TIMEOUT_SECONDS' },
+    DSM_UNINSTALL_FAILED: { code: 'DSM_UNINSTALL_FAILED', description: 'DSM reported a package stop or uninstall failure', suggestion: 'Check the reported DSM error and Package Center log' },
+    DSM_TIMEOUT_INVALID: { code: 'DSM_TIMEOUT_INVALID', description: 'A DSM timeout budget is invalid', suggestion: 'Use whole seconds from 1 to 86400 for DSM timeout variables' },
+    DSM_INSTALL_TIMEOUT: { code: 'DSM_INSTALL_TIMEOUT', description: 'The overall install/start budget was exhausted; DSM may still be working', suggestion: 'Check Package Center before retrying or increase DSM_INSTALL_TIMEOUT_SECONDS' },
+    DSM_INSTALL_FAILED: { code: 'DSM_INSTALL_FAILED', description: 'DSM reported a package installation or startup failure', suggestion: 'Check the reported DSM error and Package Center log' },
     HOST_TIMEOUT: { "code": "HOST_TIMEOUT", "description": "The NAS request timed out", "suggestion": "Check connection and firewall; inspect state before retrying writes" },
     CTL_HOST_REQUIRED: { "code": "CTL_HOST_REQUIRED", "description": "Select a registered NAS host", "suggestion": "Run synopkgland host add, select --host, or set host default" },
     CTL_NOT_AUTHENTICATED: { "code": "CTL_NOT_AUTHENTICATED", "description": "The DSM session is absent or expired", "suggestion": "Run synopkgland host login <name>" },

package/dist/host/catalog-install.d.ts

@@ -32,19 +32,24 @@ export interface UploadedCatalogPackage {
 }
 export declare function packageStateFromRecord(value: unknown): InstalledPackageState;
 export declare function packageStateFromListPayload(payload: unknown, packageId: string): InstalledPackageState | undefined;
-export declare function fetchInstalledPackageState(dsmOrigin: string, cookieHeader: string, packageId: string): Promise<InstalledPackageState | undefined>;
-export declare function waitForInstalledVersion(readState: () => InstalledPackageState | undefined | Promise<InstalledPackageState | undefined>, options: {
+export declare function fetchInstalledPackageState(dsmOrigin: string, cookieHeader: string, packageId: string, timeoutMs?: number): Promise<InstalledPackageState | undefined>;
+export interface InstallWaitOptions {
     packageId: string;
     expectedVersion?: string;
     deadlineMs?: number;
     pollMs?: number;
-}): Promise<void>;
+    requireRunning?: boolean;
+    requireTransition?: boolean;
+    onProgress?: (message: string) => void;
+}
+export declare function waitForInstalledVersion(readState: (remainingMs: number) => InstalledPackageState | undefined | Promise<InstalledPackageState | undefined>, options: InstallWaitOptions): Promise<void>;
 export interface UninstallPackageOptions {
     dsmOrigin: string;
     cookieHeader: string;
     packageId: string;
     deadlineMs?: number;
     pollMs?: number;
+    onProgress?: (message: string) => void;
 }
 export declare function uninstallPackageFromDsm(options: UninstallPackageOptions): Promise<void>;
 export declare function catalogInstallationRequests(entry: Pick<CatalogPackageEntry, "package" | "version" | "size" | "beta" | "link" | "md5" | "qinst" | "deppkgs" | "breakpkgs" | "replacepkgs">, installed: boolean, sid: string, volumePath?: string): {
@@ -64,6 +69,9 @@ export interface LocalSpkInstallOptions {
     version: string;
     profileName?: string;
     extraValues?: Record<string, string>;
+    deadlineMs?: number;
+    pollMs?: number;
+    onProgress?: (message: string) => void;
 }
 export declare function installPackageFromLocalSpk(options: LocalSpkInstallOptions): Promise<void>;
 export {};

package/dist/host/catalog-install.js

@@ -1,7 +1,9 @@
 import { CtlError } from '../ctl/errors.js';
 import { readFileSync } from "node:fs";
+import { terminalSafe } from '../terminal-text.js';
 import { dsmFetch } from "./dsm-http.js";
 import { assertDsmCompoundResponse } from "./dsm-compound.js";
+import { dsmRequestTimeoutMs, dsmOperationTimeoutMs, dsmInstallTimeoutMs, dsmUninstallTimeoutMs, dsmPollIntervalMs, isHostTimeout } from '../nas/timeouts.js';
 function normalizeDeppkgs(deppkgs) {
     if (typeof deppkgs === "string") {
         const match = /^([^><=]+)(>=|>|<=|<|==)(.+)$/.exec(deppkgs.trim());
@@ -25,13 +27,13 @@ async function dsmWebApi(dsmOrigin, cookieHeader, params, options = {}) {
     const query = new URLSearchParams(params);
     const response = await dsmFetch(`${dsmOrigin}/webapi/entry.cgi?${query.toString()}`, {
         headers: { cookie: cookieHeader },
-    });
+    }, options.timeoutMs);
     const body = (await response.json());
     const errorCode = body.error?.code;
     if (!body.success &&
         !options.allowFailure &&
         !(errorCode && options.allowErrorCodes?.includes(errorCode))) {
-        throw new Error(`DSM ${params.api}/${params.method} failed: ${Number(body.error?.code) || "invalid response"}`);
+        throw new CtlError('DSM_API_FAILED', `DSM ${params.api}/${params.method} failed: ${Number(body.error?.code) || "invalid response"}${typeof body.error?.description === "string" ? ` ${body.error.description}` : ""}`, 'Check DSM permissions and Package Center');
     }
     return body;
 }
@@ -110,7 +112,7 @@ export function packageStateFromListPayload(payload, packageId) {
     }
     return packageStateFromRecord(match);
 }
-export async function fetchInstalledPackageState(dsmOrigin, cookieHeader, packageId) {
+export async function fetchInstalledPackageState(dsmOrigin, cookieHeader, packageId, timeoutMs) {
     try {
         const body = await dsmWebApi(dsmOrigin, cookieHeader, {
             api: "SYNO.Core.Package",
@@ -118,7 +120,7 @@ export async function fetchInstalledPackageState(dsmOrigin, cookieHeader, packag
             method: "list",
             additional: JSON.stringify(["status", "installed_info"]),
             ignore_hidden: "false",
-        });
+        }, { timeoutMs });
         return packageStateFromListPayload(body, packageId);
     }
     catch (error) {
@@ -133,89 +135,126 @@ function installStatusIsBroken(status) {
     }
     return /(broken|error|fail|150)/i.test(status);
 }
+function installBudgetExpired(options) {
+    const target = options.expectedVersion ? ` to reach version ${options.expectedVersion}` : ' to install from catalog';
+    return new CtlError('DSM_INSTALL_TIMEOUT', `Timed out waiting for ${options.packageId}${target}: overall install budget exhausted; DSM may still be installing/starting.`, 'Check Package Center state before retrying; the install was not replayed');
+}
 export async function waitForInstalledVersion(readState, options) {
-    const deadline = Date.now() + (options.deadlineMs ?? 15 * 60 * 1000);
-    const pollMs = options.pollMs ?? 5000;
+    const deadline = Date.now() + (options.deadlineMs ?? dsmInstallTimeoutMs());
+    const pollMs = options.pollMs ?? dsmPollIntervalMs();
+    let transitioned = !options.requireTransition;
     while (Date.now() < deadline) {
-        const state = await readState();
-        if (state?.installed && installStatusIsBroken(state.status)) {
-            throw new Error(`Package ${options.packageId} install did not complete (Package Center status ${state.status}). Check synopkg postinst / webservice acquire.`);
+        let state;
+        try {
+            state = await readState(Math.max(1, deadline - Date.now()));
         }
-        if (state?.installed && !/installing|upgrading/i.test(state.status ?? "")) {
-            if (!options.expectedVersion || state.version === options.expectedVersion) {
-                return;
-            }
+        catch (error) {
+            if (!isHostTimeout(error))
+                throw error;
+            options.onProgress?.(`${options.packageId}: status request timed out; still installing/starting…`);
         }
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        if (state && (installStatusIsBroken(state.status) ||
+            state.error && (state.error.code !== undefined ? state.error.code !== 0 : Boolean(state.error.description)))) {
+            throw new CtlError('DSM_INSTALL_FAILED', `DSM reports package ${options.packageId} install did not complete (Package Center status ${state.status ?? 'unknown'}): ${state.error?.code ?? ''} ${state.error?.description ?? state.statusDescription ?? ''}`.trim(), 'Check the DSM Package Center install/start log');
+        }
+        const running = /^(run|running)$/i.test(state?.status ?? '');
+        if (state && (!state.installed || (state.status !== undefined && !running) ||
+            (state.version !== undefined && state.version !== options.expectedVersion)))
+            transitioned = true;
+        if (Date.now() >= deadline)
+            break;
+        if (state?.installed && !/installing|upgrading|starting/i.test(state.status ?? '') &&
+            (!options.expectedVersion || state.version === options.expectedVersion) &&
+            (!options.requireRunning || running) && transitioned)
+            return;
+        options.onProgress?.(`${options.packageId}: installing/starting… (DSM status ${state?.status ?? 'unavailable'})`);
+        await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
     }
-    throw new Error(options.expectedVersion
-        ? `Timed out waiting for ${options.packageId} to reach version ${options.expectedVersion}`
-        : `Timed out waiting for ${options.packageId} to install from catalog`);
+    throw installBudgetExpired(options);
 }
 function packageStatusIsStopped(state) {
     const status = state?.status?.trim().toLowerCase();
     return state?.installed === true && (status === "stop" || status === "stopped" || status === "manually-stopped");
 }
-async function waitForPackageStopped(readState, options) {
-    const deadline = Date.now() + (options.deadlineMs ?? 5 * 60 * 1000);
-    const pollMs = options.pollMs ?? 1000;
-    while (Date.now() < deadline) {
-        const state = await readState();
-        if (packageStatusIsStopped(state)) {
-            return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
-    }
-    throw new Error(`Timed out waiting for ${options.packageId} to stop before uninstall`);
-}
-async function waitForPackageUninstalled(readState, options) {
-    const deadline = Date.now() + (options.deadlineMs ?? 5 * 60 * 1000);
-    const pollMs = options.pollMs ?? 1000;
-    while (Date.now() < deadline) {
-        const state = await readState();
-        if (state?.installed === false) {
-            return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
-    }
-    throw new Error(`Timed out waiting for ${options.packageId} to be uninstalled`);
-}
 function uninstallFailure(packageId, error) {
     const detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof CtlError)
+        return new CtlError(error.code, `Failed to uninstall ${packageId}: ${detail}`, error.hint, error.exitCode);
     const failure = new Error(`Failed to uninstall ${packageId}: ${detail}`);
     failure.code = "CATALOG_INSTALL_FAILED";
     return failure;
 }
 export async function uninstallPackageFromDsm(options) {
+    const deadline = Date.now() + (options.deadlineMs ?? dsmUninstallTimeoutMs());
+    const requestMs = dsmRequestTimeoutMs(), operationMs = dsmOperationTimeoutMs();
+    const pollMs = options.pollMs ?? dsmPollIntervalMs();
+    const progress = options.onProgress ?? (message => process.stderr.write(`${terminalSafe(message)}\n`));
+    let phase = 'checking package state';
+    const expired = () => new CtlError('DSM_UNINSTALL_TIMEOUT', `Package ${options.packageId}: overall uninstall budget exhausted while ${phase}; DSM may still be stopping/uninstalling.`, 'Check Package Center before retrying; stop/uninstall requests were not replayed');
+    const remaining = (limit) => {
+        if (Date.now() >= deadline)
+            throw expired();
+        return Math.min(limit, deadline - Date.now());
+    };
+    const heartbeat = setInterval(() => progress(`${options.packageId}: ${phase}…`), pollMs);
     try {
         const sid = extractSid(options.cookieHeader);
-        const readState = () => fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId);
-        const before = await readState();
-        if (!before)
-            throw new Error("Cannot verify package state before removal");
+        const wait = async (done) => {
+            while (Date.now() < deadline) {
+                let state;
+                try {
+                    state = await fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId, remaining(requestMs));
+                }
+                catch (error) {
+                    if (!isHostTimeout(error))
+                        throw error;
+                    progress(`${options.packageId}: status request timed out; ${phase}…`);
+                }
+                if (state && Date.now() < deadline) {
+                    if (done(state))
+                        return state;
+                    if (installStatusIsBroken(state.status) || (state.error && (state.error.code !== undefined ? state.error.code !== 0 : Boolean(state.error.description))))
+                        throw new CtlError('DSM_UNINSTALL_FAILED', `DSM reports ${options.packageId} failed while ${phase}: ${state.error?.code ?? state.status ?? ''} ${state.error?.description ?? state.statusDescription ?? ''}`, 'Check the DSM Package Center stop/uninstall log');
+                }
+                progress(`${options.packageId}: ${phase}… (DSM status ${state?.status ?? 'unavailable'})`);
+                await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+            }
+            throw expired();
+        };
+        const dispatch = async (api, method) => {
+            progress(`${options.packageId}: ${phase}…`);
+            try {
+                await dsmWebApi(options.dsmOrigin, options.cookieHeader, {
+                    api, version: '1', method, id: jsonApiParam(options.packageId), _sid: sid,
+                    ...(method === 'uninstall' ? { extra_values: jsonApiParam('{}') } : {}),
+                }, { timeoutMs: remaining(operationMs) });
+            }
+            catch (error) {
+                if (!isHostTimeout(error))
+                    throw error;
+                progress(`${options.packageId}: ${method} request timed out; checking DSM state without replay…`);
+            }
+        };
+        const before = await wait(() => true);
+        if (!before.installed)
+            return;
         if (!packageStatusIsStopped(before)) {
-            await dsmWebApi(options.dsmOrigin, options.cookieHeader, {
-                api: "SYNO.Core.Package.Control",
-                version: "1",
-                method: "stop",
-                id: jsonApiParam(options.packageId),
-                _sid: sid,
-            });
-            await waitForPackageStopped(readState, options);
+            phase = 'stopping';
+            await dispatch('SYNO.Core.Package.Control', 'stop');
+            const stopped = await wait(state => !state.installed || packageStatusIsStopped(state));
+            if (!stopped.installed)
+                return;
         }
-        await dsmWebApi(options.dsmOrigin, options.cookieHeader, {
-            api: "SYNO.Core.Package.Uninstallation",
-            version: "1",
-            method: "uninstall",
-            id: jsonApiParam(options.packageId),
-            extra_values: jsonApiParam("{}"),
-            _sid: sid,
-        });
-        await waitForPackageUninstalled(readState, options);
+        phase = 'uninstalling';
+        await dispatch('SYNO.Core.Package.Uninstallation', 'uninstall');
+        await wait(state => !state.installed);
     }
     catch (error) {
         throw uninstallFailure(options.packageId, error);
     }
+    finally {
+        clearInterval(heartbeat);
+    }
 }
 export function catalogInstallationRequests(entry, installed, sid, volumePath) {
     const install = {
@@ -297,7 +336,7 @@ export function catalogCompoundSteps(uploaded, entry, options) {
 export function catalogUpgradeCompoundSteps(uploaded, entry, extraValues) {
     return catalogCompoundSteps(uploaded, entry, { blupgrade: true, extraValues });
 }
-async function uploadLocalSpk(options, sid) {
+async function uploadLocalSpk(options, sid, timeoutMs) {
     const bytes = readFileSync(options.spkPath);
     const form = new FormData();
     form.append("api", "SYNO.Core.Package.Installation");
@@ -309,7 +348,7 @@ async function uploadLocalSpk(options, sid) {
         method: "POST",
         headers: { cookie: options.cookieHeader },
         body: form,
-    });
+    }, timeoutMs);
     const body = (await uploadResponse.json());
     if (!body.success || !body.data?.id || !body.data.task_id) {
         throw new Error(`DSM SYNO.Core.Package.Installation/upload failed: ${Number(body.error?.code) || "invalid response"}`);
@@ -317,20 +356,69 @@ async function uploadLocalSpk(options, sid) {
     return { id: body.data.id, taskId: body.data.task_id };
 }
 export async function installPackageFromLocalSpk(options) {
-    const sid = extractSid(options.cookieHeader);
-    const dsmState = await fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId);
-    const installed = dsmState?.installed === true;
-    const uploaded = await uploadLocalSpk(options, sid);
-    const compound = JSON.stringify(catalogCompoundSteps(uploaded, { version: options.version, size: readFileSync(options.spkPath).byteLength }, { blupgrade: installed, extraValues: options.extraValues }));
-    const compoundResponse = await dsmWebApi(options.dsmOrigin, options.cookieHeader, {
-        api: "SYNO.Entry.Request",
-        version: "1",
-        method: "request",
-        stop_when_error: "true",
-        mode: jsonApiParam("sequential"),
-        compound,
-        _sid: sid,
-    }, { allowFailure: true });
-    assertDsmCompoundResponse(compoundResponse);
-    await waitForInstalledVersion(async () => await fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId), { packageId: options.packageId, expectedVersion: options.version });
+    // The same wall budget covers upload, install/upgrade and startup verification.
+    const deadline = Date.now() + (options.deadlineMs ?? dsmInstallTimeoutMs());
+    const requestMs = dsmRequestTimeoutMs(), operationMs = dsmOperationTimeoutMs();
+    const pollMs = options.pollMs ?? dsmPollIntervalMs();
+    const progress = options.onProgress ?? (message => process.stderr.write(`${terminalSafe(message)}\n`));
+    let phase = 'checking package state';
+    const remaining = (limit) => {
+        if (Date.now() >= deadline)
+            throw installBudgetExpired(options);
+        return Math.min(limit, deadline - Date.now());
+    };
+    const heartbeat = setInterval(() => progress(`${options.packageId}: ${phase}…`), pollMs);
+    try {
+        const sid = extractSid(options.cookieHeader);
+        let before;
+        while (!before) {
+            try {
+                before = await fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId, remaining(requestMs));
+            }
+            catch (error) {
+                if (!isHostTimeout(error))
+                    throw error;
+            }
+            if (!before) {
+                progress(`${options.packageId}: waiting for DSM package state…`);
+                await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, remaining(requestMs))));
+            }
+        }
+        phase = 'uploading';
+        progress(`${options.packageId}: uploading…`);
+        const uploaded = await uploadLocalSpk(options, sid, remaining(operationMs));
+        const compound = JSON.stringify(catalogCompoundSteps(uploaded, { version: options.version, size: readFileSync(options.spkPath).byteLength }, { blupgrade: before.installed, extraValues: options.extraValues }));
+        phase = 'installing/starting';
+        progress(`${options.packageId}: ${phase}…`);
+        let timedOut = false;
+        try {
+            const response = await dsmWebApi(options.dsmOrigin, options.cookieHeader, {
+                api: 'SYNO.Entry.Request', version: '1', method: 'request', stop_when_error: 'true',
+                mode: jsonApiParam('sequential'), compound, _sid: sid,
+            }, { allowFailure: true, timeoutMs: remaining(operationMs) });
+            assertDsmCompoundResponse(response);
+        }
+        catch (error) {
+            if (!isHostTimeout(error))
+                throw error;
+            timedOut = true;
+            progress(`${options.packageId}: install/upgrade request timed out; DSM may still be installing/starting; checking state…`);
+        }
+        await waitForInstalledVersion(budget => fetchInstalledPackageState(options.dsmOrigin, options.cookieHeader, options.packageId, Math.min(requestMs, budget)), { packageId: options.packageId, expectedVersion: options.version,
+            deadlineMs: remaining(Number.MAX_SAFE_INTEGER), pollMs, requireRunning: true,
+            // A lost same-version reinstall reply must not accept the old running instance.
+            requireTransition: timedOut && before.installed && before.version === options.version,
+            onProgress: progress });
+    }
+    catch (error) {
+        if (isHostTimeout(error)) {
+            if (Date.now() >= deadline)
+                throw installBudgetExpired(options);
+            throw new CtlError('HOST_TIMEOUT', 'SPK upload request timed out; no install request was sent', 'Check the NAS connection and DSM_OPERATION_TIMEOUT_SECONDS before retrying');
+        }
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
 }

package/dist/host/dsm-compound.js

@@ -58,7 +58,7 @@ export function assertDsmCompoundResponse(raw) {
     const root = requireRecord(raw, "response");
     if (root.success !== true) {
         const errorCode = numericErrorCode(root.error);
-        throw new DsmCompoundError("DSM_REQUEST_FAILED", "DSM SYNO.Entry.Request compound request failed", {
+        throw new DsmCompoundError("DSM_REQUEST_FAILED", `DSM SYNO.Entry.Request compound request failed${errorSummary(root.error)}`, {
             dsmErrorCode: errorCode,
             detail: root.error ?? root,
         });
@@ -68,7 +68,7 @@ export function assertDsmCompoundResponse(raw) {
     const dependencyConflictIndex = parsed.results.findIndex((result) => result.errorCode === 4552);
     if (dependencyConflictIndex >= 0) {
         const result = parsed.results[dependencyConflictIndex];
-        throw new DsmCompoundError("DSM_DEPENDENCY_CONFLICT", `DSM ${result.api}/${result.method} rejected the package because a dependency is running`, {
+        throw new DsmCompoundError("DSM_DEPENDENCY_CONFLICT", `DSM ${result.api}/${result.method} rejected the package because a dependency is running (4552)`, {
             api: result.api,
             method: result.method,
             errorCode: result.errorCode,
@@ -80,7 +80,7 @@ export function assertDsmCompoundResponse(raw) {
     if (parsed.hasFail || firstFailureIndex >= 0) {
         const result = firstFailureIndex >= 0 ? parsed.results[firstFailureIndex] : undefined;
         throw new DsmCompoundError("DSM_COMPOUND_FAILED", result
-            ? `DSM compound step ${result.api}/${result.method} failed`
+            ? `DSM compound step ${result.api}/${result.method} failed${errorSummary(failureDetail(resultRecords[firstFailureIndex]))}`
             : "DSM compound request reported a failed step", {
             api: result?.api,
             method: result?.method,
@@ -90,6 +90,13 @@ export function assertDsmCompoundResponse(raw) {
     }
     return parsed;
 }
+function errorSummary(error) {
+    if (!isRecord(error))
+        return '';
+    const code = numericErrorCode(error);
+    const description = typeof error.description === 'string' ? error.description : '';
+    return `${code === undefined ? '' : ` (${code})`}${description ? `: ${description}` : ''}`;
+}
 function failureDetail(rawResult) {
     const result = isRecord(rawResult) ? rawResult : undefined;
     return result?.error ?? rawResult;

package/dist/images/pin.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { registryBaseUrl } from "../compose/registry-mirrors.js";
 import { readFileSync, writeFileSync } from "node:fs";
 import { isScalar, parseDocument } from "yaml";
 /**
@@ -73,18 +74,6 @@ export function parseImageReference(image) {
     }
     return { registry, repository, tag, digest, explicitTag };
 }
-function registryBaseUrl(registry) {
-    if (registry === "docker.io" || registry === "index.docker.io") {
-        return "https://registry-1.docker.io";
-    }
-    const host = registry.startsWith("[")
-        ? registry.slice(0, registry.indexOf("]") + 1)
-        : registry.split(":")[0];
-    if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") {
-        return `http://${registry}`;
-    }
-    return `https://${registry}`;
-}
 function parseBearerChallenge(header) {
     if (!header) {
         return null;
@@ -152,12 +141,13 @@ export async function resolveImageDigest(image, deps = {}) {
     if (!response.ok) {
         throw new ImageDigestError(`registry answered HTTP ${response.status} for ${image}`);
     }
+    const body = Buffer.from(await response.arrayBuffer());
+    const digest = `sha256:${createHash("sha256").update(body).digest("hex")}`;
     const header = response.headers.get("docker-content-digest");
-    if (header && DIGEST_VALUE.test(header)) {
-        return header.toLowerCase();
+    if (header && (!DIGEST_VALUE.test(header) || header.toLowerCase() !== digest)) {
+        throw new ImageDigestError(`registry content digest mismatch for ${image}`);
     }
-    const body = Buffer.from(await response.arrayBuffer());
-    return `sha256:${createHash("sha256").update(body).digest("hex")}`;
+    return digest;
 }
 /** Keep the source's quote style so only the reference text changes. */
 function quoteLike(node, value) {

package/dist/nas/auth.js

@@ -1,7 +1,7 @@
 import { CtlError } from '../ctl/errors.js';
 import { createRequest } from './transport.js';
 export async function loginDsm(origin, username, password, options) {
-    const request = options.request ?? createRequest(origin, 30000, options.ca);
+    const request = options.request ?? createRequest(origin, undefined, options.ca);
     const form = new URLSearchParams({ api: 'SYNO.API.Auth', version: '7', method: 'login', account: username, passwd: password, session: 'DSM', format: 'cookie', enable_syno_token: 'yes', enable_device_token: options.remember === false ? 'no' : 'yes', device_name: 'synopkgland', device_id: options.deviceId ?? '' });
     let result = await request('/webapi/entry.cgi', form);
     if (result?.error?.code === 402) {

package/dist/nas/connection.js

@@ -6,7 +6,7 @@ export async function connectNas(name) {
     const credentials = resolveHostCredentials(name);
     const session = await credentials.loadSession();
     registerDsmSession(session, credentials.hostName, credentials.ca, credentials.fingerprint, credentials.tls);
-    const request = createRequest(session.origin, 62000, credentials.ca, credentials.tls);
+    const request = createRequest(session.origin, undefined, credentials.ca, credentials.tls);
     return {
         name: credentials.hostName,
         session,

package/dist/nas/http.d.ts

@@ -2,4 +2,4 @@ import { type DsmSession } from './transport.js';
 import type { HostTls } from './tls.js';
 export declare function registerDsmSession(session: DsmSession, name: string, ca?: string, fingerprint?: string, policy?: HostTls): void;
 /** All DSM fetch callers, including session-only automation, use the NAS socket policy. */
-export declare function dsmFetch(url: string, init?: RequestInit): Promise<Response>;
+export declare function dsmFetch(url: string, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/dist/nas/http.js

@@ -9,12 +9,12 @@ export function registerDsmSession(session, name, ca, fingerprint, policy) {
     policies.set(session.origin, trust);
 }
 /** All DSM fetch callers, including session-only automation, use the NAS socket policy. */
-export async function dsmFetch(url, init = {}) {
+export async function dsmFetch(url, init = {}, timeoutMs) {
     const headers = new Headers(init.headers), origin = new URL(url).origin;
     const cookie = headers.get('cookie') ?? '';
     // App cookies can accompany a DSM cookie; keep its token and TLS policy.
     const binding = [...bindings.values()].find(b => b.session.origin === origin && cookie.split(/;\s*/).includes(b.session.cookie));
-    const response = await sessionFetch(url, { ...init, headers }, binding ? { ...binding.session, cookie } : undefined, undefined, binding?.trust ?? policies.get(origin));
+    const response = await sessionFetch(url, { ...init, headers }, binding ? { ...binding.session, cookie } : undefined, undefined, binding?.trust ?? policies.get(origin), timeoutMs);
     if (response.status >= 300 && response.status < 400)
         throw new CtlError('CTL_HTTP_ERROR', `HTTP ${response.status}; redirects are never followed`, 'Check the NAS URL', 6);
     if (binding && new URL(url).pathname === '/webapi/entry.cgi') {

package/dist/nas/store.js

@@ -99,7 +99,7 @@ export class CtlStore {
         if (!options.storedOnly && process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
             if (process.env.DSM_USERNAME !== host.username)
                 throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Automation account differs from the registered host.', 'Use the registered account or a separately named host.', 2);
-            session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, 30000, undefined, this.trust(host)) });
+            session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, undefined, undefined, this.trust(host)) });
         }
         else
             session = await this.credentials.get(this.key(host));

package/dist/nas/timeouts.d.ts

@@ -0,0 +1,7 @@
+export declare const dsmRequestTimeoutMs: () => number;
+export declare const dsmOperationTimeoutMs: () => number;
+export declare const dsmUninstallTimeoutMs: () => number;
+export declare const dsmInstallTimeoutMs: () => number;
+export declare const dsmPollIntervalMs: () => number;
+export declare function isHostTimeout(error: unknown): boolean;
+export declare function dsmApiTimeoutMs(api: string | null, method: string | null): number;

package/dist/nas/timeouts.js

@@ -0,0 +1,24 @@
+import { CtlError } from '../ctl/errors.js';
+/** Seconds in the existing DSM_* automation environment (also loaded from .env). */
+function seconds(name, fallback) {
+    const value = process.env[name];
+    if (value === undefined)
+        return fallback * 1000;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > 86400)
+        throw new CtlError('DSM_TIMEOUT_INVALID', `${name} must be a whole number of seconds from 1 to 86400`, 'Set a positive DSM timeout budget');
+    return Number(value) * 1000;
+}
+export const dsmRequestTimeoutMs = () => seconds('DSM_REQUEST_TIMEOUT_SECONDS', 180);
+export const dsmOperationTimeoutMs = () => seconds('DSM_OPERATION_TIMEOUT_SECONDS', 600);
+export const dsmUninstallTimeoutMs = () => seconds('DSM_UNINSTALL_TIMEOUT_SECONDS', 1800);
+export const dsmInstallTimeoutMs = () => seconds('DSM_INSTALL_TIMEOUT_SECONDS', 1800);
+export const dsmPollIntervalMs = () => seconds('DSM_POLL_INTERVAL_SECONDS', 5);
+export function isHostTimeout(error) {
+    return error instanceof CtlError && error.code === 'HOST_TIMEOUT';
+}
+export function dsmApiTimeoutMs(api, method) {
+    const longOperation = api === 'SYNO.Entry.Request' || api === 'SYNO.Core.Package.Uninstallation' ||
+        (api === 'SYNO.Core.Package.Installation' && ['upload', 'install'].includes(method ?? '')) ||
+        (api === 'SYNO.Core.Package.Control' && ['start', 'stop'].includes(method ?? ''));
+    return longOperation ? dsmOperationTimeoutMs() : dsmRequestTimeoutMs();
+}

package/dist/nas/tls.js

@@ -1,3 +1,4 @@
+import { dsmRequestTimeoutMs } from './timeouts.js';
 import tls from "node:tls";
 import https from "node:https";
 import { isIP } from "node:net";
@@ -47,7 +48,7 @@ export function probeCertificate(origin, options = {}) {
             ...socketOptions(origin, options.ca),
             rejectUnauthorized: false,
         });
-        const timer = setTimeout(() => socket.destroy(timeoutError()), options.timeoutMs ?? 30000);
+        const timer = setTimeout(() => socket.destroy(timeoutError()), options.timeoutMs ?? dsmRequestTimeoutMs());
         socket.once("error", (e) => reject(networkError(e)));
         socket.once("close", () => clearTimeout(timer));
         socket.once("secureConnect", () => {

package/dist/nas/transport.d.ts

@@ -11,7 +11,7 @@ export interface DsmSession {
 }
 export type JsonRequest = (path: string, body: URLSearchParams | Record<string, unknown>, session?: DsmSession) => Promise<any>;
 export declare function canonicalOrigin(input: string, tunnel?: boolean): string;
-export declare function createRequest(origin: string, timeoutMs?: number | (() => number), ca?: string, trust?: HostTls): JsonRequest;
-export declare function sessionFetch(url: string, init: RequestInit, session: DsmSession | undefined, ca?: string, trust?: HostTls): Promise<Response>;
+export declare function createRequest(origin: string, timeoutMs?: number | (() => number) | undefined, ca?: string, trust?: HostTls): JsonRequest;
+export declare function sessionFetch(url: string, init: RequestInit, session: DsmSession | undefined, ca?: string, trust?: HostTls, timeoutMs?: number): Promise<Response>;
 /** The only Node HTTP dispatch for NAS endpoints, including streaming transfers. */
 export declare function nasHttpRequest(url: URL, options: http.RequestOptions, timeoutMs: number, trust: HostTls | undefined, listener: (res: http.IncomingMessage) => void): http.ClientRequest;

package/dist/nas/transport.js

@@ -6,6 +6,7 @@ import { assertSessionActive } from './session.js';
 import { nasOptions } from './options.js';
 import { readFileSync } from 'node:fs';
 import { CtlError } from '../ctl/errors.js';
+import { dsmRequestTimeoutMs, dsmApiTimeoutMs } from './timeouts.js';
 export const CTL_TIMEOUT_MS = 62000;
 export const APP_COOKIE = Symbol("ctlAppCookie");
 export function canonicalOrigin(input, tunnel = false) {
@@ -20,11 +21,12 @@ export function canonicalOrigin(input, tunnel = false) {
         throw new CtlError('CTL_URL_INVALID', 'Use HTTPS, or explicit --ssh-tunnel for a loopback HTTP tunnel.', 'run: synopkgland host add <name> --url https://<nas>:5001');
     return url.origin;
 }
-export function createRequest(origin, timeoutMs = CTL_TIMEOUT_MS, ca, trust) {
+export function createRequest(origin, timeoutMs = undefined, ca, trust) {
     return async (path, body, session) => {
         if (!path.startsWith('/') || path.startsWith('//') || path.includes('?') || path.includes('#') || path.includes('\\') || path.includes('%') || path.split('/').some(p => p === '.' || p === '..'))
             throw new CtlError('CTL_PATH_INVALID', 'Unsafe request path.', 'run: synopkgland ctl list --refresh');
-        const remaining = typeof timeoutMs === 'function' ? timeoutMs() : timeoutMs;
+        const params = body instanceof URLSearchParams ? body : undefined;
+        const remaining = typeof timeoutMs === 'function' ? timeoutMs() : timeoutMs ?? (path === '/webapi/entry.cgi' ? dsmApiTimeoutMs(params?.get('api') ?? null, params?.get('method') ?? null) : CTL_TIMEOUT_MS);
         if (remaining <= 0)
             throw new CtlError('CTL_NETWORK', 'Request budget exhausted before dispatch.', 'Check App state before retrying writes.', 6);
         const url = new URL(path, origin);
@@ -91,7 +93,10 @@ export function createRequest(origin, timeoutMs = CTL_TIMEOUT_MS, ca, trust) {
         });
     };
 }
-export async function sessionFetch(url, init, session, ca, trust) {
+export async function sessionFetch(url, init, session, ca, trust, timeoutMs) {
+    const targetUrl = new URL(url);
+    const params = init.body instanceof URLSearchParams ? init.body : targetUrl.searchParams;
+    timeoutMs ??= targetUrl.pathname === '/webapi/entry.cgi' ? dsmApiTimeoutMs(params.get('api'), params.get('method')) : dsmRequestTimeoutMs();
     if (session && new URL(url).origin !== session.origin)
         throw new CtlError('CTL_ORIGIN_MISMATCH', 'Credentials cannot cross NAS origins', 'Check the registered NAS origin', 4);
     const headers = new Headers(init.headers);
@@ -102,14 +107,14 @@ export async function sessionFetch(url, init, session, ca, trust) {
     const request = new Request(url, { ...init, headers }), bytes = init.body ? Buffer.from(await request.arrayBuffer()) : undefined;
     return new Promise((resolve, reject) => {
         const target = new URL(url);
-        const req = nasHttpRequest(target, { method: request.method, headers: Object.fromEntries(request.headers) }, 62000, trustWithCa(trust, ca), res => {
+        const req = nasHttpRequest(target, { method: request.method, headers: Object.fromEntries(request.headers) }, timeoutMs, trustWithCa(trust, ca), res => {
             const chunks = [];
             let length = 0;
             res.on('data', c => { length += c.length; if (length > 16 * 1024 * 1024)
                 res.destroy(new CtlError('CTL_RESPONSE_TOO_LARGE', 'DSM response exceeds 16 MiB', 'Use a narrower operation', 5));
             else
                 chunks.push(c); });
-            res.on('error', () => reject(new CtlError('DSM_NETWORK', 'DSM response interrupted', 'Check the NAS connection', 6)));
+            res.on('error', e => reject(e instanceof CtlError ? e : new CtlError('DSM_NETWORK', 'DSM response interrupted', 'Check the NAS connection', 6)));
             res.on('end', () => { const headers = new Headers(); for (const [k, v] of Object.entries(res.headers))
                 for (const x of Array.isArray(v) ? v : [v])
                     if (x !== undefined)
@@ -121,7 +126,7 @@ export async function sessionFetch(url, init, session, ca, trust) {
         else
             request.signal.addEventListener('abort', abort, { once: true });
         req.once('close', () => request.signal.removeEventListener('abort', abort));
-        const timer = setTimeout(() => req.destroy(timeoutError()), 62000);
+        const timer = setTimeout(() => req.destroy(timeoutError()), timeoutMs);
         req.once('close', () => clearTimeout(timer));
         req.on('timeout', () => req.destroy(timeoutError()));
         req.on('error', e => reject(networkError(e)));

package/dist/standalone/compose.js

@@ -1,3 +1,4 @@
+import { composeRegistryMirrors } from "../compose/registry-mirrors.js";
 import { portDefaults } from './install-ports.js';
 import { validComposeAppData } from "../runtime/compose-data.js";
 import { composeDiagnosisMessages, renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
@@ -126,10 +127,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
                 install_settings: context.installSettings,
                 install_ports: context.installPorts,
                 resolve_images: context.resolveImages === true,
-                registry_mirrors: context.resolveImages &&
-                    process.env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS
-                    ? JSON.parse(process.env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS)
-                    : undefined,
+                registry_mirrors: context.resolveImages ? composeRegistryMirrors() : undefined,
                 architecture: context.architecture,
                 image_proofs: context.imageProofs,
             }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.41.9",
+  "version": "0.41.10",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {