@synopackageland/cli 0.41.10 → 0.41.11

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.41.11 (2026-10-30)
+
+- Pre-pull inspected Compose image references on the NAS with byte progress, a
+  configurable 20-minute no-progress watchdog and image/registry/cause diagnostics.
+  Keep the shared tolerant install budget and never replay timed-out writes.
+- Uninstall broken packages directly, tolerate only their pre-existing install
+  failure while waiting for removal, and preserve new DSM worker failures.
+- Accept explicit DSM denial signals for admin-only window smoke; add optional
+  `preReady.clickIfVisible` for one-click upstream interstitials.
+- Force IPv4 and noninteractive SSH tunnels with bounded connection and shutdown.
+- Add `logs --json`, DSM worker messages and masked, timestamped last pull errors.
+  Clarify that smoke needs e2e/web/Chromium but no AI provider peers.
+
 ## 0.41.10 (2026-10-30)
 
 - Give DSM reads/login three minutes and SPK upload, install/upgrade and package

package/README.md

@@ -223,7 +223,8 @@ not change how the App runs or its privilege tier. See `synopkgland skill show b
 
 `@synopackageland/cli/e2e` holds the DSM helpers for a package's real-NAS
 suite on [`e2e`](https://www.npmjs.com/package/e2e) and `@e2e-dev/web`
-(optional peers, with `ai` and `@ai-sdk/openai`).
+(optional peers). Smoke needs `e2e`, `@e2e-dev/web` and its Chromium browser;
+`ai` and `@ai-sdk/openai` are needed only when calling `magpieAgent()`.
 
 `dsmTarget()` uses Chromium and accepts self-signed DSM and gateway HTTPS
 certificates by default, including redirects from an HTTP DSM URL. It configures
@@ -276,12 +277,19 @@ import { appOpenSmoke } from '@synopackageland/cli/e2e';
 appOpenSmoke({ ready: '[data-app-ready]' });
 ```
 
+Declare an optional one-click upstream interstitial in the smoke config, for example
+`preReady: {clickIfVisible: {text: 'Continue on this device'}, timeout: 5000}`.
+It runs before the ready wait for permitted users; absent controls are skipped,
+and click failures remain failures. Denied and anonymous tests do not run it.
+
 `ready` is an app-content CSS selector or `{text: 'Exact text'}`. The helper
 reads `dsm-package.yaml` (`app` overrides its filename) and derives the launcher
 and entry using the packaging defaults. `entry` overrides a configured Portal
 alias or ingress URL. Three tests cover administrator (A), normal user (N),
 and a fresh anonymous browser context (X). A must reach `ready`. For
-`entry: admin-only`, N must see the SDK gateway's access-denied page, with
+`entry: admin-only`, N must see the SDK gateway's access-denied page or an explicit
+DSM denial/launcher privilege signal without an App window. A timeout alone is
+not proof of denial. Both paths require
 the `ready` and App content markers absent from the DOM. Set `content` to
 an App shell selector or text marker when it differs from `ready`, for example
 `appOpenSmoke({ready: '[data-app-ready]', content: '#app'})`.
@@ -484,11 +492,28 @@ variables also work in `.env`; each accepts integer seconds from 1 to 86400:
 | --- | ---: | --- |
 | `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_INSTALL_TIMEOUT_SECONDS` | 1800 | Per-package state check, pre-pull, 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 |
+| `DSM_IMAGE_PULL_STALL_TIMEOUT_SECONDS` | 1200 | No increase in NAS pull bytes; status heartbeats do not reset this budget |
 
 For example, set `DSM_INSTALL_TIMEOUT_SECONDS=3600` for an hour per package.
+Container Apps pre-pull their inspected, locked image references on the NAS before
+SPK upload. An exact local repository digest skips the registry pull; an image
+configuration ID or a remote update digest is not sufficient proof. Progress includes bytes; failures name the image, requested registry
+and daemon cause/endpoint when DSM provides them. Configure a reachable mirror,
+trust an inspecting CA in Container Manager, or use `images pin` and preload the
+pinned image. Pinning alone does not download layers onto the NAS. Pull tasks
+are not cancelled or replayed when their response is lost or a budget expires.
+Broken packages skip stop during uninstall; their existing install error does not
+block removal, while new uninstall errors still fail clearly.
+
+`logs --json` emits the usual single JSON envelope, including DSM `worker_msg`,
+status details and the last reported Compose error. A locally retained pre-pull
+failure includes its source and timestamp; it is scoped to NAS origin and package
+and cleared after a successful pre-pull. An unavailable lower-level cause stays
+unknown; a generic `install_corruption` does not prove a registry failure.
+
 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

package/dist/cli.js

@@ -694,6 +694,7 @@ async function runCliWithin(argv) {
     });
     program
         .command("logs")
+        .option("--json", "Print a single JSON object")
         .description("Status diagnosis: DSM package status and masked diagnostics; does not stream application logs")
         .option("--host <name>", "Registered NAS host")
         .option("--dev", "Development Package Identity")
@@ -714,10 +715,7 @@ async function runCliWithin(argv) {
             });
         if (!result.ok)
             throw failure("NOT_INSTALLED", "The package is not installed. Run synopkgland deploy --host first.");
-        for (const line of result.lines)
-            stdout(line);
-        if (result.diagnostics)
-            stdout(JSON.stringify(result.diagnostics, null, 2));
+        emit('logs', result, [...result.lines, ...(result.diagnostics ? [JSON.stringify(result.diagnostics, null, 2)] : [])].join('\n'));
     });
     const skill = program
         .command("skill")

package/dist/e2e/app-open.d.ts

@@ -16,6 +16,11 @@ export interface AppOpenSmokeOptions {
     admin?: string;
     normal?: string;
     timeout?: number;
+    /** Optional one-click upstream interstitial; only used on entries expected ready. */
+    preReady?: {
+        clickIfVisible: SmokeMarker;
+        timeout?: number;
+    };
 }
 export interface SmokeEntry {
     package: string;

package/dist/e2e/dsm.d.ts

@@ -194,6 +194,8 @@ export declare function normalSmokeSkip(user?: string, env?: Env): string | unde
 /** Checks rendered errors as well as HTTP errors; ready alone never proves success. */
 export declare function assertSmokePage(page: Page, ready: SmokeMarker, anonymous?: boolean, publicLogin?: SmokeMarker): Promise<void>;
 /** A denied entry must show the SDK denial page and contain no App markers. */
-export declare function assertSmokeAccess(page: Page, root: Page | Locator, options: Pick<AppOpenSmokeOptions, 'ready' | 'content'>, expectation: 'ready' | 'denied', timeout: number): Promise<void>;
+export declare function assertSmokeAccess(page: Page, root: Page | Locator, options: Pick<AppOpenSmokeOptions, 'ready' | 'content' | 'preReady'>, expectation: 'ready' | 'denied', timeout: number): Promise<void>;
+/** A window may be denied by DSM before any App frame is created. */
+export declare function assertDsmWindowDenied(page: Page, appId: string, options: Pick<AppOpenSmokeOptions, 'ready' | 'content'>, dialogs: string[], timeout: number, dialogStart?: number): Promise<void>;
 /** Registers A (admin), N (manifest entry policy), X (fresh anonymous context). */
 export declare function appOpenSmoke(options: AppOpenSmokeOptions): void;

package/dist/e2e/dsm.js

@@ -52,10 +52,18 @@ export function tunnelArgs(env = process.env) {
     const target = env.DSM_E2E_SSH?.trim();
     if (!target)
         throw new Error("DSM_E2E_SSH is required to open a NAS tunnel; set it to user@nas.example (using your NAS host).");
-    return ["-N", "-o", "BatchMode=yes", "-o", "ExitOnForwardFailure=yes",
+    const timeout = tunnelTimeoutMs(env);
+    return ["-4", "-n", "-N", "-o", "BatchMode=yes", "-o", `ConnectTimeout=${Math.max(1, Math.ceil(timeout / 1000))}`,
+        "-o", "ConnectionAttempts=1", "-o", "ExitOnForwardFailure=yes",
         ...forwards(env).flatMap(([local, remote]) => ["-L", `127.0.0.1:${local}:127.0.0.1:${remote}`]),
         target];
 }
+function tunnelTimeoutMs(env) {
+    const value = Number(env.DSM_E2E_TUNNEL_TIMEOUT_MS ?? '15000');
+    if (!Number.isSafeInteger(value) || value < 1 || value > 86400000)
+        throw new Error('DSM_E2E_TUNNEL_TIMEOUT_MS must be a positive timeout of at most 86400000 ms.');
+    return value;
+}
 /** A loopback port nothing listens on now, for a tunnel that names none. */
 export function freePort() {
     return new Promise((accept, reject) => {
@@ -70,6 +78,7 @@ export function freePort() {
 function portOpen(port) {
     return new Promise(accept => {
         const socket = connect({ host: "127.0.0.1", port });
+        socket.setTimeout(500, () => { socket.destroy(); accept(false); });
         socket.once("connect", () => { socket.destroy(); accept(true); });
         socket.once("error", () => accept(false));
     });
@@ -97,13 +106,19 @@ export async function runWithTunnel(command, outer = process.env) {
     }
     const ssh = spawn(env.DSM_E2E_SSH_BIN || "ssh", args, { stdio: ["ignore", "ignore", "inherit"] });
     let sshExited = false;
+    let sshError;
+    ssh.once('error', error => { sshError = error; sshExited = true; });
     ssh.once("exit", () => { sshExited = true; });
     try {
-        const deadline = Date.now() + Number(env.DSM_E2E_TUNNEL_TIMEOUT_MS || "15000");
+        const deadline = Date.now() + tunnelTimeoutMs(env);
         for (const waiting of ports) {
             while (!(await portOpen(waiting))) {
-                if (sshExited || Date.now() > deadline)
-                    throw new Error(`The SSH tunnel to ${args.at(-1)} did not open on port ${waiting}.`);
+                if (sshError)
+                    throw new Error(`SSH tunnel spawn failed: ${sshError.message}`, { cause: sshError });
+                if (sshExited)
+                    throw new Error(`SSH tunnel exited before port ${waiting} opened; check the IPv4 host, SSH key and BatchMode authentication.`);
+                if (Date.now() >= deadline)
+                    throw new Error(`SSH tunnel connect timed out after ${tunnelTimeoutMs(env)} ms on port ${waiting}; check IPv4 resolution, routing and SSH key authentication.`);
                 await new Promise(accept => setTimeout(accept, 100));
             }
         }
@@ -134,7 +149,13 @@ export async function runWithTunnel(command, outer = process.env) {
         if (!sshExited) {
             const closed = new Promise(accept => ssh.once("exit", accept));
             ssh.kill("SIGTERM");
-            await closed;
+            const kill = setTimeout(() => ssh.kill('SIGKILL'), 500);
+            try {
+                await closed;
+            }
+            finally {
+                clearTimeout(kill);
+            }
         }
     }
 }
@@ -647,6 +668,19 @@ export async function assertSmokePage(page, ready, anonymous = false, publicLogi
 /** A denied entry must show the SDK denial page and contain no App markers. */
 export async function assertSmokeAccess(page, root, options, expectation, timeout) {
     if (expectation === 'ready') {
+        if (options.preReady) {
+            const step = marker(root, options.preReady.clickIfVisible);
+            try {
+                await step.waitFor({ state: 'visible', timeout: Math.min(options.preReady.timeout ?? 5000, timeout) });
+            }
+            catch (error) {
+                // An absent optional interstitial is fine; a closed page or transport error is not.
+                if (!(error instanceof Error) || !/timeout|not visible/i.test(error.message))
+                    throw error;
+            }
+            if (await step.isVisible())
+                await step.click({ timeout });
+        }
         await marker(root, options.ready).waitFor({ state: 'visible', timeout });
         await assertSmokePage(page, options.ready);
         return;
@@ -661,6 +695,52 @@ export async function assertSmokeAccess(page, root, options, expectation, timeou
         throw new Error('Denied app smoke reached a server error page.');
     }
 }
+/** A window may be denied by DSM before any App frame is created. */
+export async function assertDsmWindowDenied(page, appId, options, dialogs, timeout, dialogStart = 0) {
+    const deadline = Date.now() + timeout;
+    do {
+        if (await dsmLoginVisible(page))
+            throw new Error('Denied app smoke reached a login gate.');
+        if (await marker(page, options.ready).count() || await marker(page, options.content ?? options.ready).count())
+            throw new Error('Denied app smoke exposed app content or its ready marker.');
+        const signal = await page.evaluate(async (id) => {
+            const sds = window.SYNO?.SDS;
+            const instance = sds?.AppMgr?.getByAppName?.(id)?.[0];
+            const appWindow = instance?.window;
+            let privileges = sds?.AppPrivilege;
+            if (!privileges) {
+                const body = new URLSearchParams({ api: 'SYNO.Core.Desktop.Initdata', method: 'get_user_service', version: '1' });
+                if (sds?.Session?.SynoToken)
+                    body.set('SynoToken', sds.Session.SynoToken);
+                const response = await fetch('/webapi/entry.cgi', { method: 'POST', body, signal: AbortSignal.timeout(3000) }).then(r => r.json()).catch(() => undefined);
+                if (response?.success === true)
+                    privileges = response.data?.AppPrivilege;
+            }
+            return { normal: sds?.Session?.is_admin === false,
+                windowId: appWindow?.isVisible?.() ? appWindow.el?.dom?.id : null,
+                privilegeKnown: Boolean(privileges && typeof privileges === 'object' && !Array.isArray(privileges)),
+                allowed: privileges?.[id] === true };
+        }, appId);
+        if (!signal.normal)
+            throw new Error('Denied window smoke requires an explicit normal-user DSM session.');
+        if (signal.windowId) {
+            await assertSmokeAccess(page, page.locator(`#${signal.windowId}`), options, 'denied', Math.max(1, deadline - Date.now()));
+            return;
+        }
+        if (await page.locator('body').innerText().then(text => /(?:^|\n)\s*(?:50[0-9]\b|internal server error|bad gateway|service unavailable)/i.test(text)))
+            throw new Error('Denied window smoke reached a server error page.');
+        const denial = dialogs.slice(dialogStart).some(text => /not authorized|access denied|permission denied|no permission|not permitted|\u6c92\u6709\u6b0a\u9650|\u65e0\u6743|\u7121\u6b0a|\u6743\u9650\u4e0d\u8db3|\u6b0a\u9650\u4e0d\u8db3/i.test(text));
+        if (denial)
+            return;
+        if (Date.now() >= deadline) {
+            if (signal.privilegeKnown && !signal.allowed)
+                return;
+            break;
+        }
+        await new Promise(resolve => setTimeout(resolve, Math.min(100, deadline - Date.now())));
+    } while (true);
+    throw new Error('No App window appeared, but DSM supplied no explicit denial or launcher privilege signal.');
+}
 /** Registers A (admin), N (manifest entry policy), X (fresh anonymous context). */
 export function appOpenSmoke(options) {
     const entry = readSmokeEntry(options);
@@ -690,6 +770,16 @@ export function appOpenSmoke(options) {
                 failures.push(r.status()); };
             page.on('response', response);
             try {
+                if (entry.window && expectation === 'denied') {
+                    const dialogs = await handleDialogs(browser);
+                    const start = dialogs.length;
+                    await openDesktop(app);
+                    await page.evaluate(id => window.SYNO.SDS.AppLaunch(id), entry.appId);
+                    await assertDsmWindowDenied(page, entry.appId, options, dialogs, timeout, start);
+                    if (failures.length)
+                        throw new Error(`App smoke received HTTP ${failures.join(', ')}.`);
+                    return;
+                }
                 const root = entry.window ? await openApp(app, entry.appId, timeout, browser)
                     : (await handleDialogs(browser), await openPath(app, new URL(entry.entry, dsmUrl()).href), dsmPage());
                 await assertSmokeAccess(page, root, options, expectation, timeout);

package/dist/error-registry.js

@@ -5,6 +5,9 @@ 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" },
+    CONTAINER_PULL_FAILED: { code: 'CONTAINER_PULL_FAILED', description: 'NAS image pull failed or its outcome is unknown', suggestion: 'Check the image and registry detail; configure a mirror, trust the CA, or pin and preload the image' },
+    CONTAINER_PULL_STALLED: { code: 'CONTAINER_PULL_STALLED', description: 'NAS image download stopped making byte progress', suggestion: 'Check the registry mirror; inspect Container Manager before retrying or adjust DSM_IMAGE_PULL_STALL_TIMEOUT_SECONDS' },
+    CONTAINER_PULL_TIMEOUT: { code: 'CONTAINER_PULL_TIMEOUT', description: 'The overall install budget expired during image pull', suggestion: 'Inspect Container Manager before retrying or increase DSM_INSTALL_TIMEOUT_SECONDS' },
     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' },

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

@@ -72,6 +72,7 @@ export interface LocalSpkInstallOptions {
     deadlineMs?: number;
     pollMs?: number;
     onProgress?: (message: string) => void;
+    containerImages?: string[];
 }
 export declare function installPackageFromLocalSpk(options: LocalSpkInstallOptions): Promise<void>;
 export {};

package/dist/host/catalog-install.js

@@ -1,6 +1,8 @@
 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';
@@ -72,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,
     };
@@ -135,6 +138,18 @@ 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');
@@ -153,9 +168,8 @@ export async function waitForInstalledVersion(readState, options) {
                 throw error;
             options.onProgress?.(`${options.packageId}: status request timed out; still installing/starting…`);
         }
-        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');
+        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) ||
@@ -190,6 +204,7 @@ export async function uninstallPackageFromDsm(options) {
     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)
@@ -213,8 +228,8 @@ export async function uninstallPackageFromDsm(options) {
                 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');
+                    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()))));
@@ -238,7 +253,12 @@ export async function uninstallPackageFromDsm(options) {
         const before = await wait(() => true);
         if (!before.installed)
             return;
-        if (!packageStatusIsStopped(before)) {
+        const broken = packageFailure(before) && !installInProgress(before);
+        if (broken) {
+            previousFailure = failureDetail(before);
+            progress(`${options.packageId}: broken package (${previousFailure || before.status}); uninstalling directly without stop…`);
+        }
+        if (!broken && !packageStatusIsStopped(before)) {
             phase = 'stopping';
             await dispatch('SYNO.Core.Package.Control', 'stop');
             const stopped = await wait(state => !state.installed || packageStatusIsStopped(state));
@@ -384,6 +404,18 @@ export async function installPackageFromLocalSpk(options) {
                 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));

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/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>;

package/dist/host/package-diagnostics.js

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Diagnostic text is untrusted and can contain daemon URLs or echoed credentials. */
+export function maskDiagnostic(text) {
+    return text.replace(/https?:\/\/[^\s"'<>]+/gi, value => {
+        try {
+            const url = new URL(value);
+            if (!url.username && !url.password && !url.search && !url.hash)
+                return value;
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            return url.href;
+        }
+        catch {
+            return '<redacted URL>';
+        }
+    }).replace(/\b(password|passwd|token|synotoken|_sid|authorization|cookie|set-cookie)\s*[:=]\s*[^\r\n]+/gi, '$1=<redacted>');
+}
+function pathFor(origin, packageId) {
+    const key = createHash('sha256').update(new URL(origin).origin + '\0' + packageId).digest('hex');
+    return join(process.env.SYNOPKGLAND_DIAGNOSTICS_DIR ?? join(homedir(), '.cache/synopkgland/diagnostics'), key + '.json');
+}
+export function savePullFailure(origin, packageId, message) {
+    try {
+        const file = pathFor(origin, packageId);
+        if (!message) {
+            rmSync(file, { force: true });
+            return;
+        }
+        const dir = file.slice(0, file.lastIndexOf('/'));
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const temporary = `${file}.${process.pid}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ source: 'CLI NAS pre-pull', observedAt: new Date().toISOString(), message: maskDiagnostic(message) }), { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch { /* Optional diagnostic retention must not mask the install result. */ }
+}
+function readPullFailure(origin, packageId) {
+    try {
+        const value = JSON.parse(readFileSync(pathFor(origin, packageId), 'utf8'));
+        return { source: value.source, observedAt: value.observedAt, message: maskDiagnostic(String(value.message)) };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function packageDiagnostics(packageId, state, origin) {
+    const clean = (value) => typeof value === 'string' ? maskDiagnostic(value) : Array.isArray(value) ? value.map(clean)
+        : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, v]) => [key, /password|passwd|token|sid|authorization|cookie/i.test(key) ? '<redacted>' : clean(v)])) : value;
+    const worker = clean(state?.error?.workerMsg ?? []);
+    const messages = (value) => typeof value === 'string' ? [value] : Array.isArray(value) ? value.flatMap(messages)
+        : value && typeof value === 'object' ? Object.values(value).flatMap(messages) : [];
+    const lastComposeError = messages(worker).filter(line => /compose|pull|docker|x509|tls|certificate|registry/i.test(line)).at(-1);
+    return { packageIdentity: packageId, readiness: state?.status, error: clean(state?.error), worker_msg: worker,
+        statusCode: state?.statusCode, statusDescription: clean(state?.statusDescription),
+        ...(lastComposeError ? { lastComposeError } : {}),
+        ...(state?.status === 'broken' || state?.error?.code ? { lastPullError: readPullFailure(origin, packageId) } : {}), redacted: true };
+}

package/dist/log.js

@@ -1,5 +1,6 @@
 import { loadStandaloneManifest } from "./standalone/manifest.js";
 import { resolveDeployIdentity } from "./deploy/identity.js";
+import { maskDiagnostic, packageDiagnostics } from './host/package-diagnostics.js';
 export async function followProjectLogs(options) {
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
     const installed = await options.host.isPackageInstalled(identity.packageId);
@@ -10,12 +11,8 @@ export async function followProjectLogs(options) {
     const info = await options.host.getInstalledPackageState?.(identity.packageId);
     return {
         ok: true,
-        lines,
-        diagnostics: {
-            packageIdentity: identity.packageId,
-            readiness: info?.status,
-            redacted: true,
-        },
+        lines: lines.map(maskDiagnostic),
+        diagnostics: packageDiagnostics(identity.packageId, info, options.host.dsmOrigin),
     };
 }
 export async function followStandaloneLogs(options) {
@@ -31,7 +28,7 @@ export async function followStandaloneLogs(options) {
     const info = await options.host.getInstalledPackageState?.(packageIdentity);
     return {
         ok: true,
-        lines,
-        diagnostics: { packageIdentity, readiness: info?.status, redacted: true },
+        lines: lines.map(maskDiagnostic),
+        diagnostics: packageDiagnostics(packageIdentity, info, options.host.dsmOrigin),
     };
 }

package/dist/nas/timeouts.d.ts

@@ -3,5 +3,6 @@ export declare const dsmOperationTimeoutMs: () => number;
 export declare const dsmUninstallTimeoutMs: () => number;
 export declare const dsmInstallTimeoutMs: () => number;
 export declare const dsmPollIntervalMs: () => number;
+export declare const dsmPullStallTimeoutMs: () => number;
 export declare function isHostTimeout(error: unknown): boolean;
 export declare function dsmApiTimeoutMs(api: string | null, method: string | null): number;

package/dist/nas/timeouts.js

@@ -13,6 +13,7 @@ export const dsmOperationTimeoutMs = () => seconds('DSM_OPERATION_TIMEOUT_SECOND
 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 const dsmPullStallTimeoutMs = () => seconds('DSM_IMAGE_PULL_STALL_TIMEOUT_SECONDS', 1200);
 export function isHostTimeout(error) {
     return error instanceof CtlError && error.code === 'HOST_TIMEOUT';
 }

package/package.json

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

package/skills/SKILL.md

@@ -316,8 +316,12 @@ Use `appOpenSmoke` from `@synopackageland/cli/e2e`; keep one content-specific
 reuses the existing DSM credentials/profiles/tunnel, and registers administrator,
 normal-user and fresh anonymous tests. Configure `DSM_E2E_ACCOUNT_ADMIN` and
 `DSM_E2E_ACCOUNT_NORMAL` as private account files; a missing normal profile and
-credentials is a reported skip. For `entry: admin-only`, N must see the SDK
-gateway denial page with no App content or ready marker in the DOM; use
+credentials is a reported skip. Smoke needs `e2e`, `@e2e-dev/web` and Chromium;
+`ai` and `@ai-sdk/openai` are required only for `magpieAgent()`. Declare an optional
+interstitial as `preReady: {clickIfVisible: {text: "Continue on this device"}}`.
+For `entry: admin-only`, N must see the SDK gateway denial page or an explicit
+DSM denial/launcher privilege signal without an App window. Timeout alone is not
+denial. No App content or ready marker may be present in the DOM; use
 `content` for a separate App shell marker. Other entry kinds require N to
 reach `ready`; grant Application Privileges as needed. Preserve the manifest's
 entry policy when running the smoke.