@synopackageland/cli 0.41.9 → 0.41.11

package/dist/host/catalog-install.js

@@ -1,7 +1,11 @@
 import { CtlError } from '../ctl/errors.js';
 import { readFileSync } from "node:fs";
+import { terminalSafe } from '../terminal-text.js';
+import { pullContainerImages } from './container-pull.js';
+import { savePullFailure } from './package-diagnostics.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 +29,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;
 }
@@ -70,7 +74,8 @@ export function packageStateFromRecord(value) {
     const installedPath = stringValue(installedInfo.path, match.installedPath);
     const version = stringValue(match.version);
     const status = stringValue(additional.status, match.rawStatus, match.status);
-    const error = packageError(additional.error ?? match.error);
+    const error = packageError({ ...record(additional.error ?? match.error),
+        worker_msg: record(additional.error ?? match.error).worker_msg ?? record(additional.error ?? match.error).workerMsg ?? additional.worker_msg ?? match.worker_msg });
     const state = {
         installed: Boolean(installedPath) || match.installed === true,
     };
@@ -110,7 +115,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 +123,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 +138,143 @@ function installStatusIsBroken(status) {
     }
     return /(broken|error|fail|150)/i.test(status);
 }
+function packageFailure(state) {
+    return installStatusIsBroken(state.status) || state.statusCode === 150 ||
+        Boolean(state.statusCode && /broken|error|fail|corruption/i.test(state.statusDescription ?? '')) ||
+        Boolean(state.error && (state.error.code !== undefined ? state.error.code !== 0 : state.error.description));
+}
+function failureDetail(state) {
+    return [state.error?.code ?? state.statusCode, state.error?.description ?? state.statusDescription,
+        ...(state.error?.workerMsg ?? []).map(value => typeof value === 'string' ? value : JSON.stringify(value))].filter(value => value !== undefined).join(' ');
+}
+function installInProgress(state) {
+    return /^(installing|upgrading|starting)$/i.test(state.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 && !installInProgress(state) && packageFailure(state)) {
+            throw new CtlError('DSM_INSTALL_FAILED', `DSM reports package ${options.packageId} install did not complete (Package Center status ${state.status ?? 'unknown'}): ${failureDetail(state)}`.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';
+    let previousFailure;
+    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");
-        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);
+        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 (packageFailure(state) && !(phase === 'uninstalling' && previousFailure === failureDetail(state)))
+                        throw new CtlError('DSM_UNINSTALL_FAILED', `DSM reports ${options.packageId} failed while ${phase}: ${failureDetail(state) || state.status}`, '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;
+        const broken = packageFailure(before) && !installInProgress(before);
+        if (broken) {
+            previousFailure = failureDetail(before);
+            progress(`${options.packageId}: broken package (${previousFailure || before.status}); uninstalling directly without stop…`);
         }
-        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);
+        if (!broken && !packageStatusIsStopped(before)) {
+            phase = 'stopping';
+            await dispatch('SYNO.Core.Package.Control', 'stop');
+            const stopped = await wait(state => !state.installed || packageStatusIsStopped(state));
+            if (!stopped.installed)
+                return;
+        }
+        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 +356,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 +368,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 +376,81 @@ 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))));
+            }
+        }
+        if (options.containerImages?.length) {
+            phase = 'pulling container images';
+            try {
+                await pullContainerImages({ ...options, images: options.containerImages,
+                    deadlineMs: remaining(Number.MAX_SAFE_INTEGER), pollMs, onProgress: progress });
+                savePullFailure(options.dsmOrigin, options.packageId);
+            }
+            catch (error) {
+                savePullFailure(options.dsmOrigin, options.packageId, error instanceof Error ? error.message : 'Unknown pull error');
+                throw error;
+            }
+        }
+        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/container-pull.d.ts

@@ -0,0 +1,18 @@
+/** Use inspected effective references: these include the lock's digest and mirror. */
+export declare function containerImageReferences(report: {
+    compose?: {
+        images: unknown[];
+    };
+}): string[];
+interface PullOptions {
+    dsmOrigin: string;
+    cookieHeader: string;
+    images: string[];
+    deadlineMs?: number;
+    stallMs?: number;
+    pollMs?: number;
+    onProgress?: (message: string) => void;
+}
+/** Pull on the NAS, before Package Center can turn a registry failure into broken/150. */
+export declare function pullContainerImages(options: PullOptions): Promise<void>;
+export {};

package/dist/host/container-pull.js

@@ -0,0 +1,120 @@
+import { CtlError } from '../ctl/errors.js';
+import { parseImageReference } from '../images/pin.js';
+import { registryBaseUrl } from '../compose/registry-mirrors.js';
+import { terminalSafe } from '../terminal-text.js';
+import { maskDiagnostic } from './package-diagnostics.js';
+import { dsmFetch } from './dsm-http.js';
+import { dsmRequestTimeoutMs, dsmInstallTimeoutMs, dsmPollIntervalMs, dsmPullStallTimeoutMs, isHostTimeout } from '../nas/timeouts.js';
+/** Use inspected effective references: these include the lock's digest and mirror. */
+export function containerImageReferences(report) {
+    return [...new Set((report.compose?.images ?? []).map(value => {
+            const reference = value && typeof value === 'object' ? value.reference : undefined;
+            if (typeof reference !== 'string' || !parseImageReference(reference))
+                throw new CtlError('CONTAINER_PULL_FAILED', 'Invalid container image reference in inspected SPK', 'Rebuild and inspect the SPK');
+            return reference;
+        }))];
+}
+const hint = 'Configure a reachable registry mirror, trust the inspecting CA in Container Manager, or use images pin on a trusted host and preload the pinned image on the NAS. Check Container Manager before retrying; pull tasks may still be running.';
+const causePattern = /error|fail|denied|forbidden|unauthorized|x509|certificate|tls|timeout|timed out|refused|no such host|not found|too many requests|429|403|unexpected.*status/i;
+/** Pull on the NAS, before Package Center can turn a registry failure into broken/150. */
+export async function pullContainerImages(options) {
+    const deadline = Date.now() + (options.deadlineMs ?? dsmInstallTimeoutMs());
+    const stallMs = options.stallMs ?? dsmPullStallTimeoutMs();
+    const pollMs = options.pollMs ?? dsmPollIntervalMs();
+    const progress = options.onProgress ?? (line => process.stderr.write(`${terminalSafe(line)}\n`));
+    for (const image of new Set(options.images)) {
+        const parsed = parseImageReference(image);
+        if (!parsed)
+            throw new CtlError('CONTAINER_PULL_FAILED', 'Invalid container image reference', hint);
+        // Do not apply build-host mirror overrides here: the inspected reference is authoritative.
+        const requested = registryBaseUrl(parsed.registry, {});
+        const context = `Image ${image} (requested registry ${requested}; actual endpoint appears in the daemon detail when available)`;
+        const fail = (code, detail) => new CtlError(code, maskDiagnostic(`${context}: ${detail}`), hint);
+        let lastAdvance = Date.now(), downloaded = -1;
+        const remaining = () => {
+            if (Date.now() >= deadline)
+                throw fail('CONTAINER_PULL_TIMEOUT', 'overall install/pull budget exhausted; NAS pull outcome may still be pending');
+            if (Date.now() - lastAdvance >= stallMs)
+                throw fail('CONTAINER_PULL_STALLED', `no download progress for ${stallMs / 1000} seconds; NAS pull may still be running`);
+            return Math.max(1, Math.min(dsmRequestTimeoutMs(), deadline - Date.now(), stallMs - (Date.now() - lastAdvance)));
+        };
+        const call = async (method, params) => {
+            const response = await dsmFetch(`${options.dsmOrigin}/webapi/entry.cgi`, {
+                method: 'POST', headers: { cookie: options.cookieHeader, 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ api: 'SYNO.Docker.Image', version: '1', method, ...params }),
+            }, remaining());
+            const body = await response.json();
+            if (!response.ok || body?.success !== true) {
+                const error = body?.error;
+                throw fail('CONTAINER_PULL_FAILED', `Container Manager ${method}: HTTP ${response.status}, DSM ${error?.code ?? 'unknown'} ${typeof error?.description === 'string' ? error.description : ''}; cause unknown if not supplied by DSM`);
+            }
+            return body.data;
+        };
+        progress(`${context}: starting NAS image pull…`);
+        // Even while a NAS request is pending, keep stderr alive.
+        const heartbeat = setInterval(() => progress(`${context}: pulling… (${Math.max(0, downloaded)} bytes)`), pollMs);
+        try {
+            if (parsed.digest) {
+                const inventory = await call('list', { offset: '0', limit: '-1' });
+                const cached = Array.isArray(inventory?.images) && inventory.images.some((entry) => {
+                    if (typeof entry?.repository !== 'string' || typeof entry.digest !== 'string')
+                        return false;
+                    const local = parseImageReference(`${entry.repository}@${entry.digest}`);
+                    return local?.registry === parsed.registry && local.repository === parsed.repository && local.digest === parsed.digest;
+                });
+                if (cached) {
+                    progress(`${context}: pinned digest already present on NAS; no registry pull needed`);
+                    continue;
+                }
+            }
+            let task;
+            try {
+                task = await call('pull_start', { repository: `${parsed.registry}/${parsed.repository}`, tag: parsed.digest ?? parsed.tag });
+            }
+            catch (error) {
+                if (isHostTimeout(error))
+                    throw fail('CONTAINER_PULL_FAILED', 'pull_start response timed out; outcome unknown, request not replayed and package install not sent');
+                throw error;
+            }
+            if (typeof task?.task_id !== 'string' || !task.task_id)
+                throw fail('CONTAINER_PULL_FAILED', 'invalid pull_start response: task_id missing');
+            lastAdvance = Date.now();
+            while (true) {
+                remaining();
+                let state;
+                try {
+                    state = await call('pull_status', { task_id: task.task_id });
+                }
+                catch (error) {
+                    if (!isHostTimeout(error))
+                        throw error;
+                    progress(`${context}: status request timed out; checking existing pull task…`);
+                }
+                if (state !== undefined) {
+                    if (typeof state?.finished !== 'boolean')
+                        throw fail('CONTAINER_PULL_FAILED', 'invalid pull_status response: finished missing');
+                    const detail = typeof state.description === 'string' ? state.description : '';
+                    if (state.error || state.downloaded < 0 || causePattern.test(detail))
+                        throw fail('CONTAINER_PULL_FAILED', detail || 'daemon reported a pull error; cause unknown');
+                    if (typeof state.downloaded === 'number' && Number.isFinite(state.downloaded) && state.downloaded > downloaded) {
+                        downloaded = state.downloaded;
+                        lastAdvance = Date.now();
+                    }
+                    progress(maskDiagnostic(`${context}: ${state.finished ? 'pull complete' : 'pulling'} (${Math.max(0, downloaded)} bytes)${detail ? ` — ${detail}` : ''}`));
+                    remaining();
+                    if (state.finished)
+                        break;
+                }
+                await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, remaining())));
+            }
+        }
+        catch (error) {
+            if (error instanceof CtlError && error.code.startsWith('CONTAINER_PULL_'))
+                throw error;
+            throw fail('CONTAINER_PULL_FAILED', `NAS image pull failed: ${error instanceof Error ? error.message : 'unknown transport error'}`);
+        }
+        finally {
+            clearInterval(heartbeat);
+        }
+    }
+}

package/dist/host/dsm-client.js

@@ -1,5 +1,7 @@
 import { sessionForCredentials } from "../nas/credentials.js";
 import { CtlError } from '../ctl/errors.js';
+import { inspectAnySpk } from '../spk/inspect.js';
+import { containerImageReferences } from './container-pull.js';
 import { listShareNames, lookupSharePath, } from "./share-lookup.js";
 import { createDsmApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
 import { fetchPortInfo } from "./port-info-lookup.js";
@@ -122,6 +124,7 @@ function createDsmNasHost(credentials, profileName) {
                 version: input.version,
                 profileName,
                 extraValues: input.extraValues,
+                containerImages: containerImageReferences(await inspectAnySpk(input.spkPath)),
             });
         },
         async getExecutorStatus(packageIdentity) {

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/host/package-commands.js

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CtlError } from "../ctl/errors.js";
 import { inspectAnySpk } from "../spk/inspect.js";
+import { containerImageReferences } from './container-pull.js';
 import { connectNas, requireAdministrator, } from "./connection.js";
 import { fetchPackageSource } from "../package-source.js";
 import { fetchInstalledPackageState, installPackageFromLocalSpk, uninstallPackageFromDsm, } from "./catalog-install.js";
@@ -142,6 +143,7 @@ export async function installPackage(spec, options = {}, connection) {
         await confirm(`Install ${plan.map((e) => e.package + "@" + e.version).join(", ")}`, options.yes);
         // Download, verify and inspect the entire plan before the first NAS write.
         const files = new Map();
+        const images = new Map();
         for (const entry of plan) {
             let file = localFile;
             if (!local || entry.package !== root.package) {
@@ -159,6 +161,7 @@ export async function installPackage(spec, options = {}, connection) {
                 checked.version !== entry.version)
                 throw fail("PACKAGE_IDENTITY_MISMATCH", "Downloaded SPK identity differs from the selected release");
             files.set(entry.package, file);
+            images.set(entry.package, containerImageReferences(checked));
         }
         for (const entry of plan)
             await installPackageFromLocalSpk({
@@ -167,6 +170,7 @@ export async function installPackage(spec, options = {}, connection) {
                 packageId: entry.package,
                 version: entry.version,
                 spkPath: files.get(entry.package),
+                containerImages: images.get(entry.package),
                 extraValues: entry.package === root.package ? options.param : undefined,
             });
         return {

package/dist/host/package-diagnostics.d.ts

@@ -0,0 +1,5 @@
+import type { InstalledPackageState } from './catalog-install.js';
+/** Diagnostic text is untrusted and can contain daemon URLs or echoed credentials. */
+export declare function maskDiagnostic(text: string): string;
+export declare function savePullFailure(origin: string, packageId: string, message?: string): void;
+export declare function packageDiagnostics(packageId: string, state: InstalledPackageState | undefined, origin: string): Record<string, unknown>;